ILGFUSE

Submit sales order records

POST/api/v2/sales-ordersGoods Out in Fuse

Send sales orders (Goods Out in Fuse) for fulfilment. Accepts an array of records. The whole batch is accepted with a 202, or rejected with a 400 that lists every failing record and field. Passing validation is not the same as a fulfillable order — the mandatory fields listed below must always be present, and the Standard example shows the minimal complete shape.

Examples

Complete, valid payloads for the scenarios we see most. Pick one to load it into the panel.

Values shown like YOUR_SITE are your own configuration, not literals — substitute the values from your onboarding pack. The sandbox checks shape only, so a payload can pass there and still be rejected by the warehouse.

Mandatory fieldsRequired for every customer, every time. Everything else is optional or covered by your onboarding configuration.
  • Business IDidentifiers.businessId
  • Retail IDidentifiers.customerId
  • Warehouseidentifiers.warehouse
  • Order referenceidentifiers.salesOrder
  • Classorder.class
  • Order referenceorder.customerRef
  • Customer namecustomer.name
  • Ship methodshipping.method
  • Routeshipping.route
  • Carriershipping.carrier
  • Currencyfinancial.currency
  • Line valuefinancial.lineValue
  • Line IDshipmentLines[].line
  • SKUshipmentLines[].skuId
  • Unit of measureshipmentLines[].product.unitOfMeasure
  • Quantity orderedshipmentLines[].quantities.ordered
  • Quantity requiredshipmentLines[].quantities.required
  • Address nameshipAddresses[].address.name
  • Address line 1shipAddresses[].address.line1
  • Address cityshipAddresses[].address.city
  • Address postcodeshipAddresses[].address.postcode
  • Address countryshipAddresses[].address.country
  • First nameshipContacts[].personal.firstName
  • Last nameshipContacts[].personal.lastName
  • EmailshipContacts[].contact.email
  • PhoneshipContacts[].contact.phone

Request schema

The body is an array of records in this shape. Pick a scenario above to see a complete, valid payload.

  • ▶identifiersobjectHow this order, its customer, and its warehouse placement are identified.
    • idstring
    • shipmentIdstringYour unique reference for this shipment. Reusing a value replays as the same shipment.
    • businessIdstringmandatoryYour Fuse business ID. Must match the businessId you authenticate with.
    • businessSalesOrderIdstring
    • customerIdstringmandatoryThe retail/customer account this order ships for.
    • businessCustomerIdstring
    • shippingAddressIdstring
    • invoiceAddressIdstring
    • sitestringFulfilment site code, from your onboarding configuration.
    • warehousestringmandatoryWarehouse code within the site, from your onboarding configuration.
    • ownerIdstringStock owner code, from your onboarding configuration.
    • consignmentIdstring
    • pickGroupIdstring
    • carrierIdstring
    • loadIdstring
    • salesOrderstringmandatoryYour sales-order number. One of order.customerRef or this is required — the warehouse shipment ID is derived from it.
  • ▶orderobjectOrder-level classification, references, and instructions.
    • typestring
    • classstringmandatoryYour business's outbound order class, from your onboarding configuration. Not interchangeable with the purchase-order class.
    • statusstring
    • stagestring
    • priorityPrimestring
    • priorityAllocationstringAllocation priority, where used.
    • priorityDespatchstringDespatch priority, where your operation uses prioritisation.
    • customerRefstringmandatoryThe customer-facing order reference. One of this or identifiers.salesOrder is required.
    • returnReasonstring
    • generalReasonstring
    • maintenanceIndicatorstring
    • supervisorstring
    • notesstringFree-text delivery/packing instructions, delivered to the warehouse as an instruction attachment. Use customisations for value-added services instead.
  • ▶customerobjectWho the order is for.
    • groupstringCustomer group code. Drives group-level rules such as minimum-life-on-receipt stock attribution.
    • namestringmandatoryCustomer name as it should appear on paperwork and the carrier label.
    • orderstringThe customer's own order number (secondary reference).
  • ▶locationobject
    • regionstring
    • distributionCenterstring
    • storestring
  • ▶ownershipobject
    • stockStatusstring
  • ▶documentsobject
    • asnNumberstring
    • dNoteNumberstring
    • invoiceNumberstring
    • manifestNumberstring
    • billOfLadingstring
    • masterBillOfLadingstring
    • proofOfDeliverystring
  • ▶shippingobjectCarrier and routing selections.
    • methodstringmandatoryShipment-method label, matched against your configured shipment methods. An unmatched value falls back to a default rather than erroring.
    • carrierScacCodestring
    • trackingNumberstring
    • routestringmandatoryRouting code, from your onboarding configuration.
    • loadSequencestring
    • shippingLanestringShipping lane, from your onboarding configuration.
    • packStationstring
    • carrierstringmandatoryCarrier code, from your onboarding configuration.
  • ▶qualityControlobject
    • qualityControlstring
    • shortageCodestring
    • quantityVariancestring
    • cutOffIndstring
  • ▶quantitiesobject
    • linesnumber
    • lineQuantitynumber
    • stockTransferUnitQuantitynumber
    • volumenumber
    • weightnumber
    • actualWeightnumber
  • ▶tasksobject
    • countNewnumber
    • countCurrentnumber
    • countActionednumber
  • ▶timingobject
    • timeToPicknumber
    • timeToPacknumber
    • timeToChecknumber
    • timeToLoadnumber
    • timeOthernumber
    • timeToDelivernumber
  • ▶financialobjectOrder-level financials, used for invoicing, customs, and duty handling.
    • invoiceIndstring
    • currencystringmandatoryISO 4217 currency code for the order values.
    • lineValuenumbermandatoryTotal order value across lines — required for customs on export orders.
    • discountnumber
    • packingCostnumber
    • freightCostnumber
    • insurancenumber
    • chargesnumber
    • allowancesnumber
    • taxnumber
    • invoiceValuenumber
    • dutyPaidanytrue marks the order delivered-duty-paid: a duty attachment is written for the warehouse and carrier. Omitted is the same as false. If your DDP rules run in a connector they set this for you; calling the API directly, you set it per order.
  • ▶datesobjectOrder lifecycle dates.
    • createdstringISO 8601 date or date-time
    • suspendedstringISO 8601 date or date-time
    • closedstringISO 8601 date or date-time
    • dueOutstringWhen the order must leave the warehouse. Accepts an ISO 8601 date or date-time.
    • shipmentstringPlanned shipment date.
    • deliverystringISO 8601 date or date-time
    • invoicestringISO 8601 date or date-time
  • ▶indicatorsobject
    • advanceShippingNoticeIndicatorstring
    • overdueIndstring
  • ▶miscobject
    • valuesstring
  • ▶customisationsarray of objectHeader-level value-added-service instructions and attachments as name/value pairs. Names are matched case-sensitively downstream.
    • namestringAttachment/instruction type name — must match the configured production name exactly (case-sensitive).
    • valuestringThe instruction content.
  • ▶shipmentLinesarray of objectThe order lines.
    • shipmentIdstringThe shipment this line belongs to — repeat the header shipmentId.
    • linestringmandatoryLine number within the order, as a string ("1", "2", …).
    • levelstring
    • skuIdstringmandatoryThe SKU being ordered — must exist as master data first.
    • businessSKUstring
    • customerSKUstring
    • soLineIdnumber
    • ▶productobjectLine-level product details.
      • upcstring
      • upcDescriptionstring
      • categorystring
      • unitOfMeasurestringmandatoryA real warehouse unit code — "EA" is the common each/unit code; "EACH" is rejected.
    • ▶ownershipobject
      • lineOwnerstring
      • lineStockStatusstring
      • ownerIdstring
      • stockStatusstring
    • ▶quantitiesobjectLine quantities.
      • orderednumbermandatoryQuantity the customer ordered.
      • requirednumbermandatoryQuantity the warehouse should allocate — send it alongside ordered; it does not default from it.
      • allocatednumber
      • taskednumber
      • pickednumber
      • shippednumber
      • deliverednumber
      • dueOutnumber
    • ▶financialobjectLine-level pricing.
      • pricenumberUnit price, in the order currency.
      • discountnumber
      • taxRatenumber
    • ▶qualityobject
      • returnReasonstring
      • qualityControlstring
      • shortagestring
      • quantityVariancestring
    • ▶indicatorsobject
      • backOrderIndicatorstring
      • attachmentIndstring
      • specialConditionIndstring
    • ▶locationobject
      • consignmentIdstring
      • pickGroupIdstring
      • siteIdstring
      • warehousestring
    • ▶businessobject
      • businessIdstring
    • ▶timingobject
      • dateShipmentstringISO 8601 date or date-time
      • stagestring
    • ▶miscobject
      • lineValuesstring
    • ▶customisationsarray of objectLine-level value-added-service instructions (e.g. per-item personalisation).
      • namestring
      • valuestring
    • ▶extensionsobject
      • ▶shopifyobject
        • fulfillmentIdstring
  • ▶shipAddressesarray of objectDelivery address for the shipment. table is the fixed record discriminator "SHH".
    • tableenumone of "SHH"Fixed discriminator — always "SHH".
    • shipmentIdstringThe shipment this address belongs to — repeat the header shipmentId.
    • addressIdstringAddress sequence within the shipment; "1" for a single delivery address.
    • ▶addressobjectThe postal address.
      • namestringmandatoryRecipient/company name printed on the label.
      • line1stringmandatoryFirst address line.
      • line2string
      • line3string
      • citystringmandatoryCity or town.
      • statestring
      • postcodestringmandatoryPostal code.
      • countrystringmandatoryISO 3166 country code.
      • regionstring
    • ▶coordinatesobject
      • latitudenumber
      • longitudenumber
  • ▶shipContactsarray of objectDelivery contact — carriers reject bookings without one.
    • tableenumone of "SHH"Fixed discriminator — always "SHH".
    • shipmentIdstringThe shipment this contact belongs to — repeat the header shipmentId.
    • lineIdstringContact sequence within the shipment; "1" for a single contact.
    • ▶personalobjectThe contact's name.
      • titlestring
      • firstNamestringmandatoryContact first name.
      • lastNamestringmandatoryContact last name.
      • salutationstring
      • positionstring
    • ▶contactobjectHow the carrier reaches the recipient.
      • emailstringmandatoryContact email — used for carrier notifications.
      • faxstring
      • phonestringmandatoryContact phone in international format — used for delivery coordination.
      • mobilestring
      • pagerstring
    • ▶preferencesobject
      • languagestring

Headers

Request
  • AuthorizationBasic base64(businessId:apiKey)required

    HTTP Basic. Username is your businessId, password is your API key.

  • Content-Typeapplication/jsonrequired
  • x-correlation-idoptional

    Your own trace id for this request. Adopted for every log line Fuse writes while processing it, and returned as `correlationId` in the response body. Omitted: Fuse generates one.

Response
  • Content-Typeapplication/jsonrequired

    On 202.

  • Content-Typeapplication/problem+jsonrequired

    On 400, 401.

Responses

202application/json

Every record passed validation and is queued for the warehouse.

{
  "success": true,
  "recordCount": 1,
  "messageIds": [
    "11384719623456789"
  ],
  "correlationId": "550e8400-e29b-41d4-a716-446655440000"
}
Body fields
  • successbooleanIndicates if the request was successfully accepted
  • recordCountnumberNumber of records accepted for processing
  • messageIdsarray of stringPub/Sub message IDs for tracking
  • correlationIdstringCorrelation ID for request tracing
400application/problem+json

No record was accepted. Every failing record is listed, by its index in the array you sent.

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed for one or more records",
  "instance": "/api/v2/sales-orders",
  "errors": [
    {
      "index": 0,
      "errors": [
        "identifiers.businessId: Required",
        "shipmentLines.0.quantities.ordered: Expected number, received string"
      ]
    }
  ]
}
Body fields
  • typestringA URI reference that identifies the problem type
  • titlestringA short, human-readable summary of the problem type
  • statusnumberThe HTTP status code generated by the origin server for this occurrence of the problem
  • detailstringA human-readable explanation specific to this occurrence of the problem
  • instancestringA URI reference that identifies the specific occurrence of the problem
  • errorsarray of objectValidation errors (extension field for 400 Bad Request responses). For field-level validation errors (from Zod), this is an array of FieldValidationErrorDto. For batch validation errors, this is an array of RecordValidationErrorDto.
401application/problem+json

Credentials missing, malformed, or not recognised for this business.

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Unauthorized",
  "instance": "/api/v2/sales-orders"
}
Body fields
  • typestringA URI reference that identifies the problem type
  • titlestringA short, human-readable summary of the problem type
  • statusnumberThe HTTP status code generated by the origin server for this occurrence of the problem
  • detailstringA human-readable explanation specific to this occurrence of the problem
  • instancestringA URI reference that identifies the specific occurrence of the problem
  • errorsarray of objectValidation errors (extension field for 400 Bad Request responses). For field-level validation errors (from Zod), this is an array of FieldValidationErrorDto. For batch validation errors, this is an array of RecordValidationErrorDto.