ILGFUSE

Submit return goods authorisation records

POST/api/v2/return-goodsReturn Goods in Fuse

Authorise goods coming back from your customers. Accepts an array of return goods authorisation records. The whole batch is accepted with a 202, or rejected with a 400 that lists every failing record and field. The mandatory fields listed below must always be present, and the Standard example shows the minimal complete shape. Note: order.type is set by the platform — any value submitted here is ignored.

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.
  • Order referenceidentifiers.id
  • Business IDidentifiers.businessId
  • Classorder.class
  • Warehouselocation.warehouse
  • Ownerlocation.ownerId
  • Expected delivery datedates.dueIn
  • SKU IDlines[].identifiers.skuId
  • Order quantitylines[].quantities.ordered
  • Advised quantitylines[].quantities.advised

Request schema

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

  • ▶identifiersobjectHow this return is identified.
    • idstringmandatoryYour unique reference for this return authorisation.
    • queueIdstring
    • businessIdstringmandatoryYour Fuse business ID. Must match the businessId you authenticate with.
    • businessRgaNumberstringLead return reference the warehouse books the arrival against (limited to roughly 20 characters downstream).
    • customerIdstringThe returning party — a supplier code registered for your business (for some businesses this is your own business ID, for others a distinct code; confirm at onboarding).
    • businessCustomerIdstring
    • originalPurchaseOrderstringThe original order this return relates to, where known.
    • primestring
    • consignmentIdstring
    • grnNumberstring
    • manifestNumberstring
    • pocstring
    • shippingAddressIdstring
    • invoiceAddressIdstring
  • ▶orderobjectReturn classification.
    • statusstring
    • typestring
    • classstringmandatoryThe return discriminator — customer return vs wholesale return code from your onboarding configuration. This, not order.type, marks the receipt as a return.
    • stagestring
    • prioritystring
    • maintenanceIndicatorstring
  • ▶customerobjectThe end customer returning the goods.
    • groupstring
    • namestring
    • referencestringThe customer's own returns (RMA) reference.
  • ▶locationobjectWhere the return is arriving.
    • sitestringReceiving site code.
    • warehousestringmandatoryWarehouse code within the site.
    • ownerIdstringmandatoryStock owner the return books against.
    • stockStatusstring
    • regionstring
    • receiptLanestringReturns lane, where your site uses lane routing.
  • ▶shippingobject
    • methodstring
    • ▶carrierobject
      • idstring
      • trackingNumberstring
    • routestring
    • loadIdstring
    • loadSequencenumber
  • ▶qualityobjectReturn reasons and inspection.
    • qualityAssurancestring
    • acceptanceCodestring
    • variancestring
    • returnReasonstringNumeric return-reason lookup code for your account — not a descriptive string. Required at header and line level.
  • ▶quantitiesobject
    • totalLinesnumber
    • totalQuantitynumber
    • storeUnitsQuantitynumber
    • volumenumber
    • weightnumber
    • actualWeightnumber
  • ▶tasksobject
    • countNewnumber
    • countCurrentnumber
    • countActionednumber
  • ▶timesobject
    • toUnloadnumber
    • toInspectnumber
    • toPutawaynumber
    • othernumber
    • toCollectnumber
  • ▶personnelobject
    • supervisorstring
    • reasonstring
  • ▶datesobjectReturn dates.
    • createdstringISO 8601 date or date-time
    • suspendedstringISO 8601 date or date-time
    • closedstringISO 8601 date or date-time
    • collectedstringISO 8601 date or date-time
    • dueInstringmandatoryExpected arrival date.
    • arrivalstringISO 8601 date or date-time
    • receiptstringReceipt date — required at header and line level.
  • ▶indicatorsobject
    • asnstring
    • paperworkstring
    • overduestring
  • ▶metadataobjectReturn-level notes. The return carries a single note field — there is no customisations array.
    • notesstringFree-text note for the returns team (e.g. reported damage to inspect for).
  • ▶linesarray of objectThe returned lines.
    • ▶identifiersobjectLine identification.
      • returnAuthorizationIdstringThe return this line belongs to — repeat the header id.
      • lineNumberstringLine number within the return, as a string.
      • levelstring
      • idnumber
      • consignmentIdstring
      • businessIdstring
      • skuIdstringmandatoryThe SKU being returned.
      • businessSkuIdstringYour SKU code for the product — usually the same value as skuId.
      • batchIdstring
    • ▶productobjectLine-level product details.
      • unitOfMeasurestringA real warehouse unit code — "EA" is the common each/unit code; "EACH" is rejected.
      • upcDescriptionstring
    • ▶locationobjectLine-level placement overrides. owner is required whenever this block is present.
      • sitestring
      • warehousestring
      • ownerstringStock owner for this line — required whenever a line location block is present.
      • stockStatusstringReceive the returned units under a non-default stock status code (e.g. quarantine for inspection before resale).
    • ▶quantitiesobjectReturn quantities. Send both ordered and advised — ordered does not default from advised.
      • orderednumbermandatoryQuantity authorised for return.
      • advisednumbermandatoryQuantity advised as actually on its way back.
      • receivednumber
      • rejectednumber
      • dueInnumber
    • ▶qualityobjectLine-level return reason.
      • returnReasonstringNumeric return-reason lookup code — required alongside the header code.
      • qualityAssurancestring
      • acceptancestring
      • variancestring
    • ▶datesobjectLine dates.
      • receiptstringLine receipt date — required alongside the header date.
      • expirystringISO 8601 date or date-time
    • ▶metadataobject
      • ownerstring
      • stockStatusstring
      • hasAttachmentstring
      • hasSpecialConditionsstring
      • stagestring
      • backOrderIndicatorstring
  • ▶returnAddressesarray of object
    • tablestring
    • returnAuthorizationIdstring
    • addressIdstring
    • ▶addressobject
      • namestring
      • line1string
      • line2string
      • line3string
      • citystring
      • statestring
      • postcodestring
      • countrystring
      • regionstring
    • ▶coordinatesobject
      • latitudenumber
      • longitudenumber

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/return-goods",
  "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/return-goods"
}
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.