Creates up to 100 shipments and returns a label set for each one.

POST/api/{version}/Shipment/Process

A request carrying a single shipment that fails is reported as 422 Unprocessable Entity. A request carrying two or more shipments always returns 200 OK; inspect each item's customResponse.hasError to find the ones that failed.

Headers

  • AuthorizationstringRequired

    JWT Authorization header using the Bearer scheme. Example: "Authorization: Bearer {token}"

  • Idempotency-Keystring · 8–128 charsRequired

    Required. 8-128 characters of A-Z a-z 0-9 _ . : - - a GUID is the obvious choice. Retrying with the same key returns the original response instead of creating the shipments again. A retry must send the identical request body bytes: the key is bound to a hash of the raw body, so re-serializing with different property order or whitespace is rejected as a mismatch rather than replayed. Matching is case-insensitive and scoped to the calling client.

Request body

application/json Required

The shipments to create. Between 1 and 100 items.

The body is an array of object of 1–100 items. Each item has these fields.

  • shipmentReference1string · max 50 chars · nullable

    Your own reference for the shipment, for example an order number. Returned on the response so results can be matched back.

  • shipmentReference2string · max 50 chars · nullable

    A second free-text reference, for example an invoice number. Stored against the shipment only.

  • despatchDatestring (date)

    ISO date (yyyy-MM-dd). If empty, the next day (UTC) is used.

  • serviceCodestring · exactly 3 charsRequired

    Mandatory. The service code provided by your account manager. 3 characters.

  • recipientAddressobjectRequired

    Mandatory. Delivery address of the shipment.

    14 fields
    • fullNamestring · max 50 charsRequired

      Mandatory. Name of the person receiving the parcel.

    • companystring · max 50 chars · nullable

      Company name at the delivery address, when the parcel is going to a business.

    • address1string · max 50 charsRequired

      Mandatory. First line of the delivery address.

    • address2string · max 50 chars · nullable

      Second line of the delivery address.

    • address3string · max 50 chars · nullable

      Third line of the delivery address.

    • citystring · max 35 charsRequired

      Mandatory. Town or city of the delivery address.

    • postcodestring · max 10 chars · nullable

      Postcode of the delivery address. Mandatory at country level.

    • countryIsostring · max 2 charsRequired

      Mandatory. 2 character ISO country code, for example GB or US.

    • phonestring · max 15 chars · nullable

      Should follow the E.164 format.

    • emailstring · max 80 chars · nullable

      Required for different services.

    • regionstring · max 50 chars · nullable

      Region, county or state of the delivery address. Required for some carriers.

    • iossNumberstring · max 15 chars · nullable

      IOSS number to declare for the consignment, when import VAT is accounted for under the IOSS scheme.

    • vatNumberstring · max 15 chars · nullable

      Recipient VAT registration number, where the destination customs authority requires it.

    • eoriNumberstring · max 15 chars · nullable

      Recipient EORI number, used for customs clearance on business shipments.

  • senderAddressobject · nullable

    Sender address. If the sender address is missing, the default company details are used.

    14 fields
    • fullNamestring · max 50 chars · nullable

      Name of the sender, printed on the label and the customs paperwork.

    • companystring · max 50 chars · nullable

      Sender company name, printed on the label and the customs paperwork.

    • address1string · max 50 chars · nullable

      First line of the sender / return address.

    • address2string · max 50 chars · nullable

      Second line of the sender / return address.

    • address3string · max 50 chars · nullable

      Third line of the sender / return address.

    • citystring · max 35 chars · nullable

      Town or city of the sender address.

    • regionstring · max 50 chars · nullable

      Region, county or state of the sender address. Required for some carriers.

    • postcodestring · max 10 chars · nullable

      Postcode of the sender address. Mandatory at country level.

    • countryIsostring · max 2 chars · nullable

      2 character ISO country code.

    • phonestring · max 15 chars · nullable

      Should follow the E.164 format.

    • emailstring · max 80 chars · nullable

      Required for different services.

    • iossNumberstring · max 80 chars · nullable

      Sender IOSS number, used for EU import VAT on IOSS consignments.

    • vatNumberstring · max 80 chars · nullable

      Sender company VAT registration number, used on the customs paperwork.

    • eoriNumberstring · max 80 chars · nullable

      Sender EORI number, used for customs clearance.

  • createShipmentParcelsarray of object · nullable

    One or more parcels per shipment. A label is produced for each parcel.

    9 item fields
    • parcelReferencestring · max 50 chars · nullable

      Your own reference for this parcel. Stored against the parcel and available on tracking.

    • parcelWeightnumber (double)Required

      Mandatory. Parcel weight in kilos (kg).

    • parcelNumberinteger (int32) · nullable

      Parcel number within the shipment. 1 or blank.

    • parcelWidthnumber (decimal) · nullable

      Parcel width. cm default.

    • parcelHeightnumber (decimal) · nullable

      Parcel height. cm default.

    • parcelLengthnumber (decimal) · nullable

      Parcel length. cm default.

    • landedCostobject · nullable

      Landed cost quoted to the customer for this parcel. Required for international shipments.

      4 fields
      • totalAmountnumber (decimal)

        Total landed cost quoted to the customer. Decimal, up to 2 decimal places.

      • dutyAmountnumber (decimal) · nullable

        Duty portion of the landed cost. Decimal, up to 2 decimal places.

      • taxAmountnumber (decimal) · nullable

        Tax portion of the landed cost. Decimal, up to 2 decimal places.

      • currencystring · exactly 3 chars · nullable

        3 character ISO currency code.

    • shipmentCostobject · nullable

      Carriage costs charged for this parcel. Required for international shipments.

      5 fields
      • transportCostCpnumber (decimal) · nullable

        Carriage cost charged to the customer. Decimal, up to 2 decimal places.

      • transportCostSpnumber (decimal) · nullable

        Carriage cost paid to the service provider. Decimal, up to 2 decimal places.

      • salesTaxnumber (decimal) · nullable

        Sales tax charged on the carriage. Decimal, up to 2 decimal places.

      • assuranceFeesnumber (decimal) · nullable

        Assurance / protection fees charged. Decimal, up to 2 decimal places.

      • currencystring · exactly 3 chars · nullable

        3 character ISO currency code.

    • createShipmentItemsarray of object · nullable

      The goods carried in this parcel. Required for international shipments.

      16 item fields
      • countryOfOriginstring · max 2 chars · nullable

        2 character ISO code of the country the goods were made in.

      • exportTypestring · max 50 charsRequired

        Mandatory. One of Documents, Goods, Gift, Commercial samples, Returned Merchandise, Other or Dangerous Goods.

        One of: "Documents", "Goods", "Gift", "Commercial samples", "Returned Merchandise", "Other", "Dangerous Goods"

      • itemDescription1string · max 100 chars · nullable

        Plain-English description of the goods, used on the customs declaration. Avoid generic wording such as 'gift' or 'parts'.

      • skustring · max 50 chars · nullable

        Your stock keeping unit for the item.

      • harmonizationCodestring · max 10 chars · nullable

        HS commodity code. Mandatory for most countries.

      • itemReferencestring · max 50 chars · nullable

        Your own reference for this line item, for example the order line id.

      • quantityShippedinteger (int32)

        Number of units of this item in the parcel.

      • weightValuenumber (double) · nullable

        Weight of a single unit, in the unit given by WeightUnit.

      • weightUnitstring · max 5 chars · nullable

        Unit the WeightValue is expressed in. kg default.

      • currencyCodestring · max 3 chars · nullable

        3 character ISO currency code the UnitPrice is expressed in.

      • unitPricenumber (double)

        Value of a single unit, in CurrencyCode. Used for customs valuation.

      • standardisedIdentifierstring · max 50 chars · nullable

        GS1 product code - GTIN, EAN or UPC.

      • nonStandardisedIdentifierstring · max 50 chars · nullable

        Seller assigned product code - MPN.

      • imageUrlstring · max 500 chars · nullable

        URL of a product image for the item.

      • fullDescriptionstring · max 100 chars · nullable

        Full product description for the item - longer than ItemDescription1.

      • productUrlstring · max 500 chars · nullable

        URL of the product page for the item.

Responses

  • 200OKarray of object

    The batch was processed. One result per requested shipment, in the same order; check customResponse.hasError on each shipment and on each parcel. A replay of a finished request returns the original response byte for byte.

    Response headers

    • Idempotency-Replayboolean

      true when this is the stored response of an earlier request with the same Idempotency-Key. No new shipments were created.

    4 item fields
    • customResponseobject · nullable

      Outcome of the shipment as a whole.

      2 fields
      • hasErrorboolean

        True when the item could not be processed - for a shipment or a parcel that means no labels are returned for it.

      • errorMessagestring · nullable

        Reason the item failed. Empty when hasError is false.

    • shipmentReference1string · nullable

      Echo of the reference sent on the request, so each result can be matched to your order. Not echoed when the failure sits on a parcel.

    • passportIdstring (uuid) · nullable

      Ascent customs passport created for the shipment. Null when the shipment did not go through Ascent (e.g. a non US/EU destination).

    • parcelsarray of object · nullable

      One entry per parcel of the shipment, in the same order as the request.

      3 item fields
      • customResponseobject · nullable

        Outcome of this individual parcel. hasError is true when this parcel failed, even when the shipment itself succeeded.

        2 fields
        • hasErrorboolean

          True when the item could not be processed - for a shipment or a parcel that means no labels are returned for it.

        • errorMessagestring · nullable

          Reason the item failed. Empty when hasError is false.

      • parcelNumberinteger (int32)

        Returns what has been defined on the request.

      • labelsarray of object · nullable

        Documents produced for the parcel - the shipping label and, where customs requires one, the invoice.

        3 item fields
        • trackingSubNumberstring · nullable

          Carrier tracking number allocated to the parcel.

        • labelBytestring · nullable

          Base64 PDF.

        • contentTypestring · nullable

          Label or Invoice.

  • 400Bad Requestobject

    Missing, malformed or repeated Idempotency-Key; the key reused with a different body; an empty array; more than 100 shipments; or a field that fails validation. Field validation failures list the offending fields under errors. No shipments are created.

    6 fields
    • typestring · nullable
    • titlestring · nullable
    • statusinteger (int32) · nullable
    • detailstring · nullable
    • instancestring · nullable
    • errorsmap of array of string · nullable · read-only
  • 401Unauthorizedobject

    Bearer token missing or expired, or carrying no usable client id.

    5 fields
    • typestring · nullable
    • titlestring · nullable
    • statusinteger (int32) · nullable
    • detailstring · nullable
    • instancestring · nullable
  • 403Forbidden

    The token does not grant permission to create shipments. No body.

  • 409Conflictobject

    A request with the same Idempotency-Key is still being processed. Wait for Retry-After seconds, then send the same request again to collect the result. Do not start a second request with a different key: that would create the shipments twice.

    Response headers

    • Retry-Afterinteger

      Seconds to wait before retrying with the same key and body.

    5 fields
    • typestring · nullable
    • titlestring · nullable
    • statusinteger (int32) · nullable
    • detailstring · nullable
    • instancestring · nullable
  • 422Unprocessable Entityobject

    Exactly one shipment was submitted and it failed. The failed shipment is carried under shipment, in the same shape as an item of the 200 response. A request with two or more shipments always returns 200 instead.

    6 fields
    • typestring · nullable
    • titlestring · nullable
    • statusinteger (int32) · nullable
    • detailstring · nullable
    • instancestring · nullable
    • shipmentobject

      The failed shipment, in the same shape as an item of the 200 response.

      4 fields
      • customResponseobject · nullable

        Outcome of the shipment as a whole.

        2 fields
        • hasErrorboolean

          True when the item could not be processed - for a shipment or a parcel that means no labels are returned for it.

        • errorMessagestring · nullable

          Reason the item failed. Empty when hasError is false.

      • shipmentReference1string · nullable

        Echo of the reference sent on the request, so each result can be matched to your order. Not echoed when the failure sits on a parcel.

      • passportIdstring (uuid) · nullable

        Ascent customs passport created for the shipment. Null when the shipment did not go through Ascent (e.g. a non US/EU destination).

      • parcelsarray of object · nullable

        One entry per parcel of the shipment, in the same order as the request.

        3 item fields
        • customResponseobject · nullable

          Outcome of this individual parcel. hasError is true when this parcel failed, even when the shipment itself succeeded.

          2 fields
          • hasErrorboolean

            True when the item could not be processed - for a shipment or a parcel that means no labels are returned for it.

          • errorMessagestring · nullable

            Reason the item failed. Empty when hasError is false.

        • parcelNumberinteger (int32)

          Returns what has been defined on the request.

        • labelsarray of object · nullable

          Documents produced for the parcel - the shipping label and, where customs requires one, the invoice.

          3 item fields
          • trackingSubNumberstring · nullable

            Carrier tracking number allocated to the parcel.

          • labelBytestring · nullable

            Base64 PDF.

          • contentTypestring · nullable

            Label or Invoice.

  • 500Internal Server Errorobject

    The whole batch was abandoned ("System issue happened") and no shipment was created. Retry the request with the same Idempotency-Key.

    5 fields
    • typestring · nullable
    • titlestring · nullable
    • statusinteger (int32) · nullable
    • detailstring · nullable
    • instancestring · nullable

Generated from openapi/v1/openapi.yaml at commit 21510e0.