Create Shipment

Creates a new shipment in the system and generates a tracking number.

Endpoint: POST /api/shipments

Required Scope: shipments:write

Request Specification

Property	Type	Required	Description
ReferenceId	string	No	Your internal reference ID for this shipment.
DuplicatedReferenceIdControl	DuplicatedReferenceIdControl	No	How should we behave when having duplicated reference id in system. Only works if you have provided a ReferenceId.
ShippingProductId	string	Yes	ID of the shipping product to use.
ToAddress	Address	Yes	Destination address.
FromAddress	Address	Yes	Origin address.
ReturnAddress	Address	No	Address for returns.
Weight	Weight	Yes	Weight of the shipment.
Size	Dimensions	Yes	Dimensions of the shipment.
DeclaredValue	Money	No	Declared value of the shipment.
ShipDate	string	Yes	Scheduled shipping date in YYYY-MM-DD format.
ExtraServices	string[]	No	Extra services for the shipment. e.g. usps_818
Notes	string	No	Notes，maximum 200 characters.

DuplicatedReferenceIdControl enum

Property	Description
AlwaysAllow	Default behaviour, always allow duplicated reference ids in system.
AllowRecreateIfExistingShipmentFailed	If the reference id already exists, and the existing shipment is in failed state, then recreate a brand new one.
Disallow	If the reference id already exists, then reject the request.

Be cautious with duplicated reference ids:

if you allow them, you will have multilple records for the same reference id, and in the List Shipment API by querying with reference id, you will get multiples records. And you will be charged for each record if it gets tracking number successfully.

if you disallow them, you need to figure out how to handle the duplicated reference ids yourself, especially when the shipment fails to get a tracking number from our carrier. Re-submitting create request with exactly the same data as before will only get the old shipment record in this case. And re-submitting create request with same reference id but different address/weight/size information will encounter a duplicated reference id error(code OMS-SHPT-005).

Response Specification

Returns a Shipment object wrapped in Result.

Sample JSON

Request

{
  "ReferenceId": "ORDER-123",
  "ShippingProductId": "PRODUCT001",
  "ToAddress": {
    "ContactName": "John Doe",
    "Street1": "123 Main St",
    "City": "New York",
    "Province": "NY",
    "CountryCode": "US",
    "Postcode": "10001",
    "Tel": "555-0199"
  },
  "FromAddress": {
    "ContactName": "Shipper Name",
    "Street1": "456 Logistic Way",
    "City": "Los Angeles",
    "Province": "CA",
    "CountryCode": "US",
    "Postcode": "90001"
  },
  "Weight": {
    "Value": 1.3,
    "Unit": "LB"
  },
  "Size": {
    "Length": 25.4,
    "Width": 12.7,
    "Height": 7.62,
    "Unit": "IN"
  },
  "ShipDate": "2026-04-01",
  "ExtraServices": null,
  "Notes": ""
}

Response

{
  "Data": {
    "Id": "2603XSHPT00001GA",
    "AccountNo": "TEST",
    "ReferenceId": "ORDER-123",
    "ShippingProductId": "PRODUCT001",
    "ToAddress": {
      "Company": "",
      "Street1": "123 Main St",
      "Street2": "",
      "Street3": "",
      "City": "New York",
      "Province": "NY",
      "CountryCode": "US",
      "Postcode": "10001",
      "ContactName": "John Doe",
      "Tel": "555-0199",
      "Email": "",
      "TaxId": ""
    },
    "FromAddress": {
      "Company": "",
      "Street1": "456 Logistic Way",
      "Street2": "",
      "Street3": "",
      "City": "Los Angeles",
      "Province": "CA",
      "CountryCode": "US",
      "Postcode": "90001",
      "ContactName": "Shipper Name",
      "Tel": "",
      "Email": "",
      "TaxId": ""
    },
    "ReturnAddress": null,
    "Weight": {
      "Value": 1.3,
      "Unit": "LB"
    },
    "Size": {
      "Length": 25.4,
      "Width": 12.7,
      "Height": 7.62,
      "Unit": "IN"
    },
    "DeclaredValue": null,
    "ShipDate": "2026-04-01",
    "ExtraServices": null,
    "Notes": "",
    "Quote": {
      "QuotationType": "Basic",
      "Fees": [
        {
          "FeeType": "BASE",
          "Amount": 23.16
        },
        {
          "FeeType": "REGISTRATION",
          "Amount": 5.0
        },
        {
          "FeeType": "NON_STANDARD_LENGTH",
          "Amount": 4.5
        }
      ],
      "Total": 32.66,
      "Weight": 1.3,
      "DimensionalWeight": 14.808,
      "FeeWeight": 14.808,
      "FeeWeightType": "DimensionalWeight",
      "PriceZone": "8",
      "WeightUnit": "LB",
      "LengthUnit": "IN",
      "CurrencyCode": "USD"
    },
    "Carrier": {
      "Status": "Processing",
      "Barcode": "",
      "Message": ""
    },
    "TrackingNumber": "",
    "CreateAt": "2026-03-24T03:36:31Z"
  },
  "Succeeded": true,
  "Error": null,
  "CapturedValues": {}
}