---
title: "Create orders"
method: POST
path: "/orders"
tags: ["Orders"]
---

# Create orders

`POST /orders`

## Request body

- CreateOrdersRequest
  - `items` CreateOrderRequest[], required
    - `orderReference` string
    - `isRecipientABusiness` boolean — Indicates if the recipient is a business or not. Mandatory for Business senders on orders shipping from Great Britain to Northern Ireland, which require additional information for B2B shipments. (Business senders are OBA accounts and OLP accounts declaring themselves as a Business sender).
    - `recipient` RecipientDetailsRequest, required
      - `address` AddressRequest
        - `fullName` string
        - `companyName` string
        - `addressLine1` string, required
        - `addressLine2` string
        - `addressLine3` string
        - `city` string, required
        - `county` string
        - `postcode` string
        - `countryCode` string, required
      - `phoneNumber` string
      - `emailAddress` string
      - `addressBookReference` string — The presence or not of <b>addressBookReference</b> and a valid <b>recipient address object</b> in the request body will determine which of the following behaviours occur:-</br></br>1) addressBookReference <b>provided</b> and a valid recipient address object <b>provided</b> - In addition to the provided recipient address fields being used for the order creation, an existing account Address Book Reference with matching addressBookReference will be overwritten with all provided recipient address fields, including phone and email. If no existing account Address Book Reference with matching addressBookReference can be found then a new one will be created with the provided addressBookReference and address fields, including phone and email.</br>2) addressBookReference <b>provided</b> and a valid recipient address object <b>not provided</b> - An account Address Book Reference with the provided addressBookReference will be used for the order if it exists.</br>3) addressBookReference <b>not provided</b> and a valid recipient address object <b>provided</b> - All provided recipient address fields, including phone and email, will be used for the order creation.</br>4) All other scenarios will result in a validation error.
    - `sender` SenderDetailsRequest
      - `tradingName` string
      - `phoneNumber` string
      - `emailAddress` string
    - `billing` BillingDetailsRequest — <b>Billing</b> along with <b>billing.address</b> objects are required in specific case when 'Use shipping address for billing address' setting is set to 'false' and 'Recipient.AddressBookReference' is provided.
      - `address` AddressRequest
        - `fullName` string
        - `companyName` string
        - `addressLine1` string, required
        - `addressLine2` string
        - `addressLine3` string
        - `city` string, required
        - `county` string
        - `postcode` string
        - `countryCode` string, required
      - `phoneNumber` string
      - `emailAddress` string
    - `packages` ShipmentPackageRequest[]
      - `weightInGrams` integer, required
      - `packageFormatIdentifier` string, required — <b>If you have a ChannelShipper account, you can also pass the name of any of your custom package formats instead of the values below.</b><br> Enum: 'undefined', 'letter', 'largeLetter', 'smallParcel', 'mediumParcel', 'largeParcel', 'parcel', 'documents'
      - `customPackageFormatIdentifier` string — This field will be deprecated in the future. Please use 'packageFormatIdentifier' for custom package formats from ChannelShipper.
      - `dimensions` DimensionsRequest — It is not mandatory to include the dimensions field. If the dimensions field is included then the inner fields heightInMms, widthInMms and depthInMms must be specified with non-zero values.
        - `heightInMms` integer, required
        - `widthInMms` integer, required
        - `depthInMms` integer, required
      - `contents` ProductItemRequest[]
        - `name` string
        - `SKU` string — The presence or not of field <b>SKU</b> and other fields in the request body will determine which of the following behaviours occur:- <br>1) A minimum of <b>SKU</b>, <b>unitValue</b>, <b>unitWeightInGrams</b> and <b>quantity</b> provided - In addition to the provided product fields being used for the order creation, an existing account Product with matching SKU will be overwritten with all provided product parameters. If no existing account Product with matching SKU can be found then a new product will be created with the provided SKU and product parameters.<br>2) <b>SKU</b>, <b>quantity</b> provided and <b>no other fields</b> provided - An account Product with the provided SKU will be used for the order if it exists.<br>3) <b>SKU not provided</b> and a minimum of <b>unitValue</b>, <b>unitWeightInGrams</b> and <b>quantity</b> provided - All provided product fields will be used for the order creation.<br>4) All other scenarios will result in a validation error.<p>Optional for EU and USA shipments (may become mandatory in the future).</p>
        - `ReferenceId` string — The manufacturer's product reference code for the item (e.g. GTIN, EAN, UPC). <p>Optional for EU and USA shipments (may become mandatory in the future).</p>
        - `ContentsPieceURL` string — A URL linking directly to the specific product page for the item being shipped. Must point to an individual product listing, not a general shop homepage or category page. <p>Optional for USA shipments (may become mandatory in the future).</p>
        - `quantity` integer, required — The number of units in a given line
        - `unitValue` number — The price of a single unit excluding tax
        - `unitWeightInGrams` integer
        - `customsDescription` string
        - `extendedCustomsDescription` string
        - `customsCode` string
        - `originCountryCode` string
        - `customsDeclarationCategory` 'none' | 'gift' | 'commercialSample' | 'documents' | 'other' | 'returnedGoods' | 'commercialSaleOfGoods' | 'eCommerceSaleOfGoods'
        - `requiresExportLicence` boolean
        - `stockLocation` string
        - `useOriginPreference` boolean
        - `supplementaryUnits` string
        - `licenseNumber` string
        - `certificateNumber` string
    - `orderDate` string, date-time, required
    - `plannedDespatchDate` string, date-time
    - `specialInstructions` string
    - `subtotal` number, required — The total value of all the goods in the order, excluding tax. This should not include retail shipping costs
    - `shippingCostCharged` number, required — The shipping costs you charged to your customer
    - `otherCosts` number
    - `customsDutyCosts` number — Customs Duty Costs is only supported in DDP (Delivery Duty Paid) services
    - `total` number, required — The sum of order subtotal, tax and retail shipping costs
    - `currencyCode` string
    - `deliveryTerm` string — Specifies how customs duties, taxes, and handling fees are paid for international shipments.<p>Accepted values are <b>DDP, IOSS_DDP, DDU_DAP, IOSS_DDU</b>.</p><p><b>N.B. If no value is provided in this field then the delivery terms will be defaulted to DDU_DAP.</b></p><p>Optional for EU and USA shipments (may become mandatory in the future).</p>
    - `postageDetails` PostageDetailsRequest
      - `sendNotificationsTo` 'sender' | 'recipient' | 'billing'
      - `serviceCode` string
      - `carrierName` string — The name of the carrier you would like to manifest orders for. This is required if the account has multiple carriers or multiple postage location numbers, and must match the name configured in the carrier settings within the main website.
      - `serviceRegisterCode` string
      - `consequentialLoss` integer
      - `receiveEmailNotification` boolean
      - `receiveSmsNotification` boolean
      - `guaranteedSaturdayDelivery` boolean — This field has been deprecated
      - `requestSignatureUponDelivery` boolean
      - `isLocalCollect` boolean
      - `safePlace` string
      - `department` string
      - `AIRNumber` string — For B2B orders shipping from Great Britain to Northern Ireland, this field can be used to provide the Recipient UKIMs number.
      - `IOSSNumber` string
      - `requiresExportLicense` boolean
      - `commercialInvoiceNumber` string
      - `commercialInvoiceDate` string, date-time
      - `recipientEoriNumber` string
    - `tags` TagRequest[]
      - `key` string
      - `value` string
    - `label` LabelGenerationRequest — <b>Reserved for OBA customers only</b>
      - `includeLabelInResponse` boolean, required
      - `includeCN` boolean
      - `includeReturnsLabel` boolean
    - `orderTax` number — The total tax charged for the order
    - `containsDangerousGoods` boolean — Indicates that the package contents contain a dangerous goods item
    - `dangerousGoodsUnCode` string — UN Code of the dangerous goods
    - `dangerousGoodsDescription` number — Description of the dangerous goods
    - `dangerousGoodsQuantity` number — Quantity or volume of the dangerous goods
    - `importer` Importer
      - `companyName` string
      - `addressLine1` string
      - `addressLine2` string
      - `addressLine3` string
      - `city` string
      - `postcode` string
      - `country` string
      - `businessName` string
      - `contactName` string
      - `phoneNumber` string
      - `emailAddress` string
      - `vatNumber` string
      - `taxCode` string
      - `eoriNumber` string
      - `isABusiness` boolean

## Response `200`

Request Processed Successfully

- CreateOrdersResponse
  - `successCount` integer
  - `errorsCount` integer
  - `createdOrders` CreateOrderResponse[]
    - `orderIdentifier` integer, required
    - `orderReference` string
    - `createdOn` string, date-time, required
    - `orderDate` string, date-time
    - `printedOn` string, date-time
    - `manifestedOn` string, date-time
    - `shippedOn` string, date-time
    - `trackingNumber` string
    - `packages` CreatePackagesResponse[]
      - `packageNumber` integer
      - `trackingNumber` string
    - `label` string — label in format base64 string
    - `labelErrors` CreateOrderLabelErrorResponse[]
      - `message` string
      - `code` string
    - `generatedDocuments` string[]
  - `failedOrders` FailedOrderResponse[]
    - `order` CreateOrderRequest
      - `orderReference` string
      - `isRecipientABusiness` boolean — Indicates if the recipient is a business or not. Mandatory for Business senders on orders shipping from Great Britain to Northern Ireland, which require additional information for B2B shipments. (Business senders are OBA accounts and OLP accounts declaring themselves as a Business sender).
      - `recipient` RecipientDetailsRequest, required
        - `address` AddressRequest
          - `fullName` string
          - `companyName` string
          - `addressLine1` string, required
          - `addressLine2` string
          - `addressLine3` string
          - `city` string, required
          - `county` string
          - `postcode` string
          - `countryCode` string, required
        - `phoneNumber` string
        - `emailAddress` string
        - `addressBookReference` string — The presence or not of <b>addressBookReference</b> and a valid <b>recipient address object</b> in the request body will determine which of the following behaviours occur:-</br></br>1) addressBookReference <b>provided</b> and a valid recipient address object <b>provided</b> - In addition to the provided recipient address fields being used for the order creation, an existing account Address Book Reference with matching addressBookReference will be overwritten with all provided recipient address fields, including phone and email. If no existing account Address Book Reference with matching addressBookReference can be found then a new one will be created with the provided addressBookReference and address fields, including phone and email.</br>2) addressBookReference <b>provided</b> and a valid recipient address object <b>not provided</b> - An account Address Book Reference with the provided addressBookReference will be used for the order if it exists.</br>3) addressBookReference <b>not provided</b> and a valid recipient address object <b>provided</b> - All provided recipient address fields, including phone and email, will be used for the order creation.</br>4) All other scenarios will result in a validation error.
      - `sender` SenderDetailsRequest
        - `tradingName` string
        - `phoneNumber` string
        - `emailAddress` string
      - `billing` BillingDetailsRequest — <b>Billing</b> along with <b>billing.address</b> objects are required in specific case when 'Use shipping address for billing address' setting is set to 'false' and 'Recipient.AddressBookReference' is provided.
        - `address` AddressRequest
          - `fullName` string
          - `companyName` string
          - `addressLine1` string, required
          - `addressLine2` string
          - `addressLine3` string
          - `city` string, required
          - `county` string
          - `postcode` string
          - `countryCode` string, required
        - `phoneNumber` string
        - `emailAddress` string
      - `packages` ShipmentPackageRequest[]
        - `weightInGrams` integer, required
        - `packageFormatIdentifier` string, required — <b>If you have a ChannelShipper account, you can also pass the name of any of your custom package formats instead of the values below.</b><br> Enum: 'undefined', 'letter', 'largeLetter', 'smallParcel', 'mediumParcel', 'largeParcel', 'parcel', 'documents'
        - `customPackageFormatIdentifier` string — This field will be deprecated in the future. Please use 'packageFormatIdentifier' for custom package formats from ChannelShipper.
        - `dimensions` DimensionsRequest — It is not mandatory to include the dimensions field. If the dimensions field is included then the inner fields heightInMms, widthInMms and depthInMms must be specified with non-zero values.
          - `heightInMms` integer, required
          - `widthInMms` integer, required
          - `depthInMms` integer, required
        - `contents` ProductItemRequest[]
          - `name` string
          - `SKU` string — The presence or not of field <b>SKU</b> and other fields in the request body will determine which of the following behaviours occur:- <br>1) A minimum of <b>SKU</b>, <b>unitValue</b>, <b>unitWeightInGrams</b> and <b>quantity</b> provided - In addition to the provided product fields being used for the order creation, an existing account Product with matching SKU will be overwritten with all provided product parameters. If no existing account Product with matching SKU can be found then a new product will be created with the provided SKU and product parameters.<br>2) <b>SKU</b>, <b>quantity</b> provided and <b>no other fields</b> provided - An account Product with the provided SKU will be used for the order if it exists.<br>3) <b>SKU not provided</b> and a minimum of <b>unitValue</b>, <b>unitWeightInGrams</b> and <b>quantity</b> provided - All provided product fields will be used for the order creation.<br>4) All other scenarios will result in a validation error.<p>Optional for EU and USA shipments (may become mandatory in the future).</p>
          - `ReferenceId` string — The manufacturer's product reference code for the item (e.g. GTIN, EAN, UPC). <p>Optional for EU and USA shipments (may become mandatory in the future).</p>
          - `ContentsPieceURL` string — A URL linking directly to the specific product page for the item being shipped. Must point to an individual product listing, not a general shop homepage or category page. <p>Optional for USA shipments (may become mandatory in the future).</p>
          - `quantity` integer, required — The number of units in a given line
          - `unitValue` number — The price of a single unit excluding tax
          - `unitWeightInGrams` integer
          - `customsDescription` string
          - `extendedCustomsDescription` string
          - `customsCode` string
          - `originCountryCode` string
          - `customsDeclarationCategory` 'none' | 'gift' | 'commercialSample' | 'documents' | 'other' | 'returnedGoods' | 'commercialSaleOfGoods' | 'eCommerceSaleOfGoods'
          - `requiresExportLicence` boolean
          - `stockLocation` string
          - `useOriginPreference` boolean
          - `supplementaryUnits` string
          - `licenseNumber` string
          - `certificateNumber` string
      - `orderDate` string, date-time, required
      - `plannedDespatchDate` string, date-time
      - `specialInstructions` string
      - `subtotal` number, required — The total value of all the goods in the order, excluding tax. This should not include retail shipping costs
      - `shippingCostCharged` number, required — The shipping costs you charged to your customer
      - `otherCosts` number
      - `customsDutyCosts` number — Customs Duty Costs is only supported in DDP (Delivery Duty Paid) services
      - `total` number, required — The sum of order subtotal, tax and retail shipping costs
      - `currencyCode` string
      - `deliveryTerm` string — Specifies how customs duties, taxes, and handling fees are paid for international shipments.<p>Accepted values are <b>DDP, IOSS_DDP, DDU_DAP, IOSS_DDU</b>.</p><p><b>N.B. If no value is provided in this field then the delivery terms will be defaulted to DDU_DAP.</b></p><p>Optional for EU and USA shipments (may become mandatory in the future).</p>
      - `postageDetails` PostageDetailsRequest
        - `sendNotificationsTo` 'sender' | 'recipient' | 'billing'
        - `serviceCode` string
        - `carrierName` string — The name of the carrier you would like to manifest orders for. This is required if the account has multiple carriers or multiple postage location numbers, and must match the name configured in the carrier settings within the main website.
        - `serviceRegisterCode` string
        - `consequentialLoss` integer
        - `receiveEmailNotification` boolean
        - `receiveSmsNotification` boolean
        - `guaranteedSaturdayDelivery` boolean — This field has been deprecated
        - `requestSignatureUponDelivery` boolean
        - `isLocalCollect` boolean
        - `safePlace` string
        - `department` string
        - `AIRNumber` string — For B2B orders shipping from Great Britain to Northern Ireland, this field can be used to provide the Recipient UKIMs number.
        - `IOSSNumber` string
        - `requiresExportLicense` boolean
        - `commercialInvoiceNumber` string
        - `commercialInvoiceDate` string, date-time
        - `recipientEoriNumber` string
      - `tags` TagRequest[]
        - `key` string
        - `value` string
      - `label` LabelGenerationRequest — <b>Reserved for OBA customers only</b>
        - `includeLabelInResponse` boolean, required
        - `includeCN` boolean
        - `includeReturnsLabel` boolean
      - `orderTax` number — The total tax charged for the order
      - `containsDangerousGoods` boolean — Indicates that the package contents contain a dangerous goods item
      - `dangerousGoodsUnCode` string — UN Code of the dangerous goods
      - `dangerousGoodsDescription` number — Description of the dangerous goods
      - `dangerousGoodsQuantity` number — Quantity or volume of the dangerous goods
      - `importer` Importer
        - `companyName` string
        - `addressLine1` string
        - `addressLine2` string
        - `addressLine3` string
        - `city` string
        - `postcode` string
        - `country` string
        - `businessName` string
        - `contactName` string
        - `phoneNumber` string
        - `emailAddress` string
        - `vatNumber` string
        - `taxCode` string
        - `eoriNumber` string
        - `isABusiness` boolean
    - `errors` CreateOrderErrorResponse[]
      - `errorCode` integer
      - `errorMessage` string
      - `fields` OrderFieldResponse[]
        - `fieldName` string
        - `value` string

## Other responses

- `400` — Bad Request (Request has missing or invalid parameters and cannot be parsed)
- `401` — Unauthorized
- `500` — Internal Server Error

---

[API](https://skmtc.net/royalmail/apis/channelshipper-royal-mail-public-api.md) · [All operations](https://skmtc.net/royalmail/apis/channelshipper-royal-mail-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/royalmail/channelshipper-royal-mail-public-api/versions/7e0c23c81719/schema)