POST
/
shipments
/
create-order-shipment
Create shipment for an existing allocation
curl --request POST \
  --url https://api.fabric.inc/v3/shipments/create-order-shipment \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-fabric-channel-id: <x-fabric-channel-id>' \
  --header 'x-fabric-tenant-id: <x-fabric-tenant-id>' \
  --data '{
  "shipmentNumber": 78974156816152,
  "shipmentExternalId": "123k4h123k",
  "poNumber": 1125,
  "vendorId": 56,
  "statusCode": "SHIPMENT_CREATED",
  "type": "STANDARD",
  "subtype": "COD",
  "reshipmentReasonCode": "Order is missing",
  "shippedAt": "2023-04-06T07:58:30.996Z",
  "locationNumber": 132412,
  "locationType": "DC",
  "totalCartons": 2,
  "masterTrackingNumber": "TX112345678",
  "shipToId": "sg6683620405",
  "shipToAddress": {
    "addressLine1": "123 Main St.",
    "addressLine2": "Suite 100",
    "addressLine3": "Seventh floor",
    "addressLine4": "Attention: Pat E. Kake",
    "city": "Seattle",
    "countryCode": "US",
    "email": "test@example.com",
    "latitude": 47.6205,
    "longitude": -122.3493,
    "name": {
      "firstName": "Alex",
      "lastName": "Doe",
      "middleName": "E"
    },
    "phone": {
      "number": "123-456-7890",
      "type": "MOBILE"
    },
    "postalCode": "98121",
    "region": "WA",
    "type": "Home"
  },
  "recipients": [
    {
      "email": "support@example.inc",
      "name": {
        "firstName": "Alex",
        "lastName": "Doe",
        "middleName": "E"
      },
      "phone": {
        "number": "123-456-7890",
        "type": "MOBILE"
      }
    }
  ],
  "attributes": {
    "attribute1": "value"
  },
  "cartons": [
    {
      "cartonNumber": 1,
      "cartonType": "Package",
      "promisedDeliveryDate": "2023-03-26T07:58:30.996Z",
      "estimatedShipDate": "2023-03-25T07:58:30.996Z",
      "estimatedDeliveryDate": "2023-03-26T07:58:30.996Z",
      "shipmentMethod": "ground",
      "shipmentCarrier": "FEDEX",
      "weight": 500,
      "trackingNumber": "1Z999AA10123456784",
      "trackingURL": "https://fedex.com/tracking",
      "tracking": [
        {
          "event": "picked up",
          "eventId": "627963716b19511e8a3a631b",
          "eventRecordedAt": "2019-09-30T07:58:30.996Z",
          "location": "Reno, NV",
          "notes": {
            "description": "Shipment picked up"
          },
          "shipmentCarrier": "FEDEX"
        }
      ],
      "items": [
        {
          "attributes": {
            "attribute1": "value"
          },
          "fees": [
            {
              "amount": 34.56,
              "name": "RETURN_FEE",
              "reason": "Return fee",
              "type": "FEE"
            }
          ],
          "giftCards": [
            {
              "amount": 50,
              "giftCardNumber": "453456765"
            }
          ],
          "itemId": 100023,
          "lineItemId": "1",
          "orderId": "6413e370cb0dc859b6c0dcb0",
          "orderNumber": "309020213",
          "shipmentExternalId": "123k4h123k",
          "orderedQuantity": 2,
          "refundAmount": 10,
          "returnQuantity": 1,
          "returnRequestCounter": 1,
          "segment": "segment",
          "shippedQuantity": 2,
          "sku": "SKU0023",
          "uom": "EA",
          "vendorId": "56"
        }
      ]
    }
  ],
  "scratchedItems": [
    {
      "orderId": "6413e370cb0dc859b6c0dcb0",
      "orderNumber": 309020213,
      "orderExternalId": "123k4h123k",
      "lineItemId": 2,
      "itemId": 100043,
      "sku": "SKU00043",
      "quantity": 1,
      "uom": "EA",
      "reasonCode": "ReasonCode23454",
      "subReasonCode": "SubReasonCode23242",
      "attributes": {
        "attribute1": "value"
      }
    }
  ]
}'
{
  "allocationId": "6413e3d3fd03a35efccb426e",
  "auditLogs": [
    {
      "auditId": "a05b72dc-78d8-4ea4-90fc-2fe6a1fe1111",
      "auditType": "CANCEL",
      "auditedAt": "2023-03-12T09:24:54.804Z",
      "employeeId": "6227",
      "lineItemId": "b03b72dc-78d8-4ea4-90fc-2fe6a1fe6569",
      "note": "Note",
      "reasonCode": "Scratched item",
      "source": "POS",
      "subReasonCode": "Scratched item",
      "updatedFields": [
        {
          "fieldName": "UOM",
          "fieldOriginalValue": "PK"
        }
      ]
    }
  ],
  "cartons": [
    {
      "cartonNumber": "1",
      "cartonType": "Package",
      "estimatedDeliveryDate": "2023-04-26T07:58:30.996Z",
      "estimatedShipmentDate": "2023-03-25T07:58:30.996Z",
      "items": [
        {
          "fees": [
            {
              "amount": 34.56,
              "name": "RETURN_FEE",
              "reason": "Return fee",
              "type": "FEE"
            }
          ],
          "giftCards": [
            {
              "amount": 50,
              "giftCardActivatedAt": "2023-04-26T07:58:30.996Z",
              "giftCardActivationRequestedAt": "2023-03-26T07:58:30.996Z",
              "giftCardNumber": "453456765",
              "giftCardStatus": "ACTIVE"
            }
          ],
          "itemId": 100023,
          "lineItemId": "1",
          "orderId": "6413e370cb0dc859b6c0dcb0",
          "orderNumber": "309020213",
          "orderedQuantity": 2,
          "refundAmount": 10,
          "returnQuantity": 1,
          "segment": "segment",
          "shipmentLineItemId": "607f1f77bcf86cd799439011",
          "shippedQuantity": 2,
          "sku": "SKU0023",
          "uom": "EA",
          "vendorId": "vend12346667"
        }
      ],
      "promisedDeliveryDate": "2023-03-26T07:58:30.996Z",
      "shipmentCarrier": "FEDEX",
      "shipmentMethod": "ground",
      "tracking": [
        {
          "event": "picked up",
          "eventId": "627963716b19511e8a3a631b",
          "eventRecordedAt": "2019-09-30T07:58:30.996Z",
          "location": "Reno, NV",
          "notes": {
            "description": "Shipment picked up"
          },
          "shipmentCarrier": "FEDEX"
        }
      ],
      "trackingNumber": "1Z999AA10123456784",
      "trackingURL": "https://example.com/tracking",
      "weight": "500 grams"
    }
  ],
  "createdAt": "2023-04-06T07:58:30.996Z",
  "invoiceId": "63ef4360aafa8a7f5247fe48",
  "locationNumber": "WH334",
  "locationType": "DC",
  "masterTrackingNumber": "TX112345678",
  "orderNumbers": [
    "309020213, 459020213"
  ],
  "poNumber": "1125",
  "recipients": [
    {
      "email": "support@example.inc",
      "name": {
        "firstName": "Alex",
        "lastName": "Doe",
        "middleName": "E"
      },
      "phone": {
        "number": "123-456-7890",
        "type": "MOBILE"
      }
    }
  ],
  "reshipmentReasonCode": "Order is missing",
  "scratchedItems": [
    {
      "itemId": 100043,
      "lineItemId": "2",
      "orderId": "6413e370cb0dc859b6c0dcb0",
      "quantity": 1,
      "reasonCode": "ReasonCode23454",
      "sku": "SKU00043",
      "subReasonCode": "SubReasonCode23242",
      "uom": "EA"
    }
  ],
  "shipToAddress": {
    "addressLine1": "123 Main St.",
    "addressLine2": "Suite 100",
    "addressLine3": "Seventh floor",
    "addressLine4": "Attention: Pat E. Kake",
    "city": "Seattle",
    "countryCode": "US",
    "email": "test@example.com",
    "latitude": 47.6205,
    "longitude": -122.3493,
    "name": {
      "firstName": "Alex",
      "lastName": "Doe",
      "middleName": "E"
    },
    "phone": {
      "number": "123-456-7890",
      "type": "MOBILE"
    },
    "postalCode": "98121",
    "region": "WA",
    "type": "Home"
  },
  "shipToId": "1",
  "shipmentId": "627963716b19511e8a3a631b",
  "shipmentNumber": "78974156816152",
  "shipmentExternalId": "123k4h123k",
  "shippedAt": "2023-04-06T07:58:30.996Z",
  "statusCode": "SHIPMENT_CREATED",
  "subtype": "COD",
  "totalCartons": 2,
  "type": "STANDARD",
  "updatedAt": "2023-04-06T07:58:30.996Z",
  "vendorId": "56",
  "version": 2
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
x-fabric-tenant-id
string
required

A header used by fabric to identify the tenant making the request. You must include tenant id in the authentication header for an API request to access any of fabric’s endpoints. You can retrieve the tenant id , which is also called account id, from Copilot. This header is required.

​
x-fabric-channel-id
string
required

x-fabric-channel-id identifies the sales channel where the API request is being made; primarily for multichannel use cases. The channel ids are 12 corresponding to US and 13 corresponding to Canada. The default channel id is 12. This field is required.

​
x-fabric-request-id
string

Unique request ID

Body

application/json

Request payload to create a shipment for an order.

​
shipmentNumber
string
required

Unique shipment identifier defined by the merchant.

Example:

78974156816152

​
shipmentExternalId
string

Unique shipment identifier defined by the merchant. This value can be used to track or reconcile shipments in external systems and serves as a reference between fabric and the merchant's order management or fulfillment system.

Example:

"123k4h123k"

​
poNumber
string

Merchant-defined purchase order number associated with the shipment.

Example:

1125

​
vendorId
string

Vendor identifier. In dropshipping scenarios, indicates the vendor responsible for fulfilling the shipment.

Example:

56

​
statusCode
enum<string>

Current status of the shipment.

Available options:
SHIPMENT_CREATED,
SHIPMENT_UPDATED,
SHIPMENT_CANCELLED,
PICKUP_CREATED,
PICKUP_COMPLETED,
SHIPMENT_RETURN_PENDING,
SHIPMENT_RETURN_RECEIVED,
SHIPMENT_PARTIALLY_DELIVERED,
SHIPMENT_DELIVERED,
SHIPMENT_ERROR
Example:

"SHIPMENT_CREATED"

​
type
enum<string>

Type of shipment.

Available options:
STANDARD,
RESHIP,
RETURN,
SCRATCH,
PENDING_RETURN,
PICKUP,
TRANSFER
Example:

"STANDARD"

​
subtype
string

Free-form text to provide an additional classification for the shipment, if required.

Example:

"COD"

​
reshipmentReasonCode
string

Code indicating the reason for a reshipment.

Example:

"Order is missing"

​
shippedAt
string<date-time>

UTC timestamp indicating when the shipment was created or shipped.

Example:

"2023-04-06T07:58:30.996Z"

​
locationNumber
string

Identifier of the ship-from location. Must match the locationNumber stored in the fabric Location service.

Example:

132412

​
locationType
string

Type of the ship-from location (for example, distribution center (DC) or warehouse). Must match the value stored in the fabric Location service.

Example:

"DC"

​
totalCartons
integer

Total number of cartons included in the shipment.

Example:

2

​
masterTrackingNumber
string

Carrier-provided master tracking number that applies to all cartons in the shipment.

Example:

"TX112345678"

​
shipToId
string

Ship-to identifier generated in the response of the Create Shipping endpoint in the Shipping service.

Example:

"sg6683620405"

​
shipToAddress
object

Address details

​
recipients
object[]

List of recipients for the shipment.

​
attributes
object

Merchant-defined custom attributes, represented as key-value pairs. Useful for storing additional information.

Example:
{ "attribute1": "value" }
​
cartons
object[]

Details of cartons included in the shipment.

​
scratchedItems
object[]

Details of items marked as scratched from the shipment.

Response

Created

Shipment details

​
version
integer
required

The current version of the shipment document. This integer indicates the number of times the shipment has been updated by any operation.

Example:

2

​
allocationId
string

System-generated allocation ID (UUID) from the Create allocation endpoint of fabric Allocation service. It refers to the given shipment. Note: Allocation occurs prior to Shipment Creation. allocationId is mandatory to create a Shipment.

Example:

"6413e3d3fd03a35efccb426e"

​
auditLogs
object[]

Audit log details

​
cartons
object[]

Carton details

​
createdAt
string<date-time>

Shipment creation time (UTC)

Example:

"2023-04-06T07:58:30.996Z"

​
invoiceId
string

Invoice ID generated from fabric Invoice service during shipment creation. Note: Invoices are only created for Shipments where merchants have payment Capture at Shipment feature enabled. The value will be “Null” if merchants don't have “Capture at Shipment” feature enabled.

Example:

"63ef4360aafa8a7f5247fe48"

​
locationNumber
string

Unique value to identify ship-from location. This must be the locationNumber stored in the fabric Location service.

Example:

"WH334"

​
locationType
string

Location type, such as distribution center (DC) or warehouse

Example:

"DC"

​
masterTrackingNumber
string

Master tracking number for all cartons in the shipment

Example:

"TX112345678"

​
orderNumbers
string[]

List of order numbers associated with a shipment. Note: Currently, a shipment can be associated with only one order. In the future, this property will support a scenario where a customer places a second order for the same product immediately after their first order. Multiple order numbers can be linked to one shipment in such cases.

​
poNumber
string

Merchant-defined purchase order number

Example:

"1125"

​
recipients
object[]

Recipient details

​
reshipmentReasonCode
string

The reshipment reason code.

Example:

"Order is missing"

​
scratchedItems
object[]

Details of scratched items

​
shipToAddress
object

Address details

​
shipToId
string

Ship-to ID generated in the response of Create shipping endpoint of Shipping service

Example:

"1"

​
shipmentId
string

System-generated shipment ID (UUID)

Example:

"627963716b19511e8a3a631b"

​
shipmentNumber
string

Merchant-defined unique shipment identifier. Note: It can be optionally generated by fabric by using resource generator feature in the Configuration service

Example:

"78974156816152"

​
shipmentExternalId
string

Unique shipment identifier defined by the merchant. This value can be used to track or reconcile shipments in external systems and serves as a reference between fabric and the merchant's order management or fulfillment system.

Example:

"123k4h123k"

​
shippedAt
string<date-time>

Order shipment time (UTC)

Example:

"2023-04-06T07:58:30.996Z"

​
statusCode
enum<string>

Current shipment status (fabric-defined codes). Note: For standard shipments, the status would be SHIPMENT_CREATED. For pickup shipment, the initial status would be PICKUP_CREATED and once the customer picks up, the status changes to PICKUP_COMPLETED

Available options:
SHIPMENT_CREATED,
SHIPMENT_UPDATED,
SHIPMENT_CANCELLED,
PICKUP_CREATED,
PICKUP_COMPLETED,
SHIPMENT_DELIVERED,
SHIPMENT_RETURN_PENDING,
SHIPMENT_RETURN_RECEIVED,
SHIPMENT_PARTIALLY_DELIVERED
Example:

"SHIPMENT_CREATED"

​
subtype
string

Shipment subtype, for another layer of classification. There are no pre-defined values; the possible value is Cash On Delivery (COD)

Example:

"COD"

​
totalCartons
integer

Total number of cartons in the given shipment. There can be only one carton per trackingNumber.

Example:

2

​
type
enum<string>

Shipment types

Available options:
STANDARD,
RESHIP,
RETURN,
SCRATCH,
PENDING_RETURN,
PICKUP,
TRANSFER
Example:

"STANDARD"

​
updatedAt
string<date-time>

Time of last update to shipment (UTC)

Example:

"2023-04-06T07:58:30.996Z"

​
vendorId
string

Vendor ID. Applicable in dropshipping scenarios to indicate the vendor responsible for the given item.

Example:

"56"