Royal Mail Orders API

openapi: 3.2.0
info:
  title: ChannelShipper & Royal Mail Public Labels Orders API
  description: Import your orders, retrieve your orders and generate labels.
  version: 1.0.0
servers:
- url: /api/v1
tags:
- name: Orders
paths:
  /orders/{orderIdentifiers}:
    get:
      tags:
      - Orders
      summary: Retrieve specific orders
      operationId: GetSpecificOrdersAsync
      parameters:
      - $ref: '#/components/parameters/orderIdentifiers'
      responses:
        '200':
          description: Return list of specific orders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GetOrderInfoResource'
        '400':
          description: Bad Request (Request has missing or invalid parameters and cannot be parsed)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderErrorResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - Bearer: []
    delete:
      tags:
      - Orders
      summary: Delete orders
      description: 'Please be aware labels generated on orders which are deleted are no longer valid and must be destroyed.


        Cancelled label information is automatically shared with Royal Mail Revenue Protection, and should

        a cancelled label be identified on an item in the Royal Mail Network, you will be charged on your account

        and an additional handling fee applied.

        '
      operationId: DeleteOrdersAsync
      parameters:
      - $ref: '#/components/parameters/orderIdentifiers'
      responses:
        '200':
          description: Provides a list of deleted orders references and ids and errors for orders that failed to delete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteOrdersResource'
        '400':
          description: Bad Request (Request has missing or invalid parameters and cannot be parsed)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderErrorInfo'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (Feature not available)
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - Bearer: []
  /orders/status:
    put:
      tags:
      - Orders
      summary: Set order status
      operationId: UpdateOrdersStatusAsync
      responses:
        '200':
          description: Provides a list of orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateOrderStatusResponse'
        '400':
          description: Bad Request (Request has missing or invalid parameters and cannot be parsed)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderUpdateError'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - Bearer: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrdersStatusRequest'
        description: 'At least one of ''orderIdentifier'' and ''orderReference'' is required. Providing both is disallowed to avoid ambiguity.


          When the status is set to ''despatchedByOtherCourier'', if the optional parameter ''trackingNumber'' is provided

          then the parameters ''despatchDate'', ''shippingCarrier'' and ''shippingService'' are also required.

          The maximum collection length is 100.

          '
        required: true
  /orders/{orderIdentifiers}/full:
    get:
      tags:
      - Orders
      summary: Retrieve details of the specific orders
      description: Reserved for ChannelShipper customers only.
      operationId: GetSpecificOrdersWithDetailsAsync
      parameters:
      - $ref: '#/components/parameters/orderIdentifiers'
      responses:
        '200':
          description: Return detailed information about the orders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GetOrderDetailsResource'
        '400':
          description: Bad Request (Request has missing or invalid parameters and cannot be parsed)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (Feature not available)
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - Bearer: []
  /orders:
    get:
      tags:
      - Orders
      summary: Retrieve pageable list of orders
      operationId: GetOrdersAsync
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/startDateTime'
      - $ref: '#/components/parameters/endDateTime'
      - $ref: '#/components/parameters/continuationToken'
      responses:
        '200':
          description: Return pageable list of orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetOrdersResponse'
        '400':
          description: Bad Request (Request has missing or invalid parameters and cannot be parsed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - Bearer: []
    post:
      tags:
      - Orders
      summary: Create orders
      operationId: CreateOrdersAsync
      responses:
        '200':
          description: Request Processed Successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrdersResponse'
        '400':
          description: Bad Request (Request has missing or invalid parameters and cannot be parsed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - Bearer: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrdersRequest'
        required: true
  /orders/full:
    get:
      tags:
      - Orders
      summary: Retrieve pageable list of orders with details
      description: Reserved for ChannelShipper customers only.
      operationId: GetOrdersWithDetailsAsync
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/startDateTime'
      - $ref: '#/components/parameters/endDateTime'
      - $ref: '#/components/parameters/continuationToken'
      responses:
        '200':
          description: Return a pageable list of orders with details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetOrdersDetailsResponse'
        '400':
          description: Bad Request (Request has missing or invalid parameters and cannot be parsed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (Feature not available)
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - Bearer: []
components:
  schemas:
    ErrorResponse:
      required:
      - message
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: string
    ProductItemRequest:
      required:
      - quantity
      type: object
      properties:
        name:
          type: string
          maxLength: 800
        SKU:
          type: string
          maxLength: 100
        quantity:
          format: int32
          type: integer
          minimum: 1
          maximum: 999999
        unitValue:
          type: number
          format: decimal
          multipleOf: 0.01
          minimum: 0
          maximum: 999999
        unitWeightInGrams:
          type: integer
          minimum: 0
          maximum: 999999
        customsDescription:
          type: string
          maxLength: 50
        extendedCustomsDescription:
          type: string
          maxLength: 300
        customsCode:
          type: string
          maxLength: 10
        originCountryCode:
          type: string
          maxLength: 3
        customsDeclarationCategory:
          type: string
          enum:
          - none
          - gift
          - commercialSample
          - documents
          - other
          - returnedGoods
          - commercialSaleOfGoods
          - eCommerceSaleOfGoods
        requiresExportLicence:
          type: boolean
        stockLocation:
          type: string
          maxLength: 50
        useOriginPreference:
          type: boolean
        supplementaryUnits:
          type: string
          maxLength: 17
        licenseNumber:
          type: string
          maxLength: 41
        certificateNumber:
          type: string
          maxLength: 41
    GetOrderInfoResource:
      required:
      - orderIdentifier
      - createdOn
      type: object
      properties:
        orderIdentifier:
          type: integer
        orderReference:
          type: string
        createdOn:
          type: string
          format: date-time
        orderDate:
          type: string
          format: date-time
        printedOn:
          type: string
          format: date-time
        manifestedOn:
          type: string
          format: date-time
        shippedOn:
          type: string
          format: date-time
        trackingNumber:
          type: string
        packages:
          type: array
          items:
            $ref: '#/components/schemas/CreatePackagesResponse'
    CreateOrderErrorResponse:
      type: object
      properties:
        errorCode:
          type: integer
        errorMessage:
          type: string
        fields:
          type: array
          items:
            $ref: '#/components/schemas/OrderFieldResponse'
    CreatePackagesResponse:
      type: object
      properties:
        packageNumber:
          type: integer
        trackingNumber:
          type: string
    Importer:
      type: object
      properties:
        companyName:
          type: string
          maxLength: 100
        addressLine1:
          type: string
          maxLength: 100
        addressLine2:
          type: string
          maxLength: 100
        addressLine3:
          type: string
          maxLength: 100
        city:
          type: string
          maxLength: 100
        postcode:
          type: string
          maxLength: 20
        country:
          type: string
          maxLength: 100
        businessName:
          type: string
          maxLength: 100
        contactName:
          type: string
          maxLength: 100
        phoneNumber:
          type: string
          maxLength: 25
        emailAddress:
          type: string
          maxLength: 254
        vatNumber:
          type: string
          maxLength: 15
        taxCode:
          type: string
          maxLength: 25
        eoriNumber:
          type: string
          maxLength: 18
        isABusiness:
          type: boolean
    CreateOrderLabelErrorResponse:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
    DeletedOrderInfo:
      type: object
      properties:
        orderIdentifier:
          type: integer
        orderReference:
          type: string
        orderInfo:
          type: string
    GetOrdersDetailsResponse:
      type: object
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/GetOrderDetailsResource'
        continuationToken:
          type: string
    CreateOrderRequest:
      required:
      - recipient
      - orderDate
      - subtotal
      - shippingCostCharged
      - total
      type: object
      properties:
        orderReference:
          maxLength: 40
          type: string
        isRecipientABusiness:
          type: boolean
        recipient:
          $ref: '#/components/schemas/RecipientDetailsRequest'
        sender:
          $ref: '#/components/schemas/SenderDetailsRequest'
        billing:
          $ref: '#/components/schemas/BillingDetailsRequest'
        packages:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentPackageRequest'
        orderDate:
          format: date-time
          type: string
        plannedDespatchDate:
          format: date-time
          type: string
        specialInstructions:
          type: string
          maxLength: 500
        subtotal:
          type: number
          format: decimal
          multipleOf: 0.01
          minimum: 0
          maximum: 999999
        shippingCostCharged:
          type: number
          format: decimal
          multipleOf: 0.01
          minimum: 0
          maximum: 999999
        otherCosts:
          type: number
          format: decimal
          multipleOf: 0.01
          minimum: 0
          maximum: 999999
        customsDutyCosts:
          type: number
          format: decimal
          multipleOf: 0.01
          minimum: 0
          maximum: 99999.99
        total:
          format: decimal
          multipleOf: 0.01
          type: number
          minimum: 0
          maximum: 999999
        currencyCode:
          type: string
          maxLength: 3
        postageDetails:
          $ref: '#/components/schemas/PostageDetailsRequest'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/TagRequest'
        label:
          $ref: '#/components/schemas/LabelGenerationRequest'
        orderTax:
          format: decimal
          multipleOf: 0.01
          type: number
          minimum: 0
          maximum: 999999
        containsDangerousGoods:
          type: boolean
        dangerousGoodsUnCode:
          type: string
          maxLength: 4
        dangerousGoodsDescription:
          type: number
          maxLength: 500
        dangerousGoodsQuantity:
          type: number
        importer:
          $ref: '#/components/schemas/Importer'
    GetTagDetailsResult:
      type: object
      properties:
        key:
          type: string
          maxLength: 100
        value:
          type: string
          maxLength: 100
    DimensionsRequest:
      type: object
      required:
      - heightInMms
      - widthInMms
      - depthInMms
      properties:
        heightInMms:
          type: integer
          format: int32
        widthInMms:
          type: integer
          format: int32
        depthInMms:
          type: integer
          format: int32
    BillingDetailsRequest:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/AddressRequest'
        phoneNumber:
          maxLength: 25
          type: string
        emailAddress:
          maxLength: 254
          type: string
    ShipmentPackageRequest:
      required:
      - weightInGrams
      - packageFormatIdentifier
      type: object
      properties:
        weightInGrams:
          format: int32
          maximum: 30000
          minimum: 1
          type: integer
        packageFormatIdentifier:
          type: string
          description: 'Enum: ''undefined'', ''letter'', ''largeLetter'', ''smallParcel'', ''mediumParcel'', ''largeParcel'', ''parcel'', ''documents'''
        customPackageFormatIdentifier:
          type: string
        dimensions:
          $ref: '#/components/schemas/DimensionsRequest'
        contents:
          type: array
          items:
            $ref: '#/components/schemas/ProductItemRequest'
    OrderUpdateError:
      type: object
      properties:
        orderIdentifier:
          type: integer
        orderReference:
          type: string
        status:
          type: string
        code:
          type: string
        message:
          type: string
    UpdateOrderStatusResponse:
      type: object
      properties:
        updatedOrders:
          type: array
          items:
            $ref: '#/components/schemas/UpdatedOrderInfo'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/OrderUpdateError'
    GetShippingDetailsResult:
      required:
      - shippingCost
      type: object
      properties:
        shippingCost:
          type: number
        trackingNumber:
          type: string
        shippingTrackingStatus:
          type: string
        serviceCode:
          type: string
        shippingService:
          type: string
        shippingCarrier:
          type: string
        receiveEmailNotification:
          type: boolean
        receiveSmsNotification:
          type: boolean
        guaranteedSaturdayDelivery:
          type: boolean
        requestSignatureUponDelivery:
          type: boolean
        isLocalCollect:
          type: boolean
        shippingUpdateSuccessDate:
          type: string
          format: date-time
        packages:
          type: array
          items:
            $ref: '#/components/schemas/CreatePackagesResponse'
    UpdatedOrderInfo:
      type: object
      properties:
        orderIdentifier:
          type: integer
        orderReference:
          type: string
        status:
          type: string
          description: Current status of the order
    OrderFieldResponse:
      type: object
      properties:
        fieldName:
          type: string
        value:
          type: string
    RecipientDetailsRequest:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/AddressRequest'
        phoneNumber:
          maxLength: 25
          type: string
        emailAddress:
          maxLength: 254
          type: string
        addressBookReference:
          maxLength: 100
          type: string
    PostageDetailsRequest:
      type: object
      properties:
        sendNotificationsTo:
          type: string
          enum:
          - sender
          - recipient
          - billing
        serviceCode:
          type: string
          maxLength: 10
        carrierName:
          type: string
          maxLength: 50
        serviceRegisterCode:
          type: string
          maxLength: 2
        consequentialLoss:
          type: integer
          format: int32
          minimum: 0
          maximum: 10000
        receiveEmailNotification:
          type: boolean
        receiveSmsNotification:
          type: boolean
        guaranteedSaturdayDelivery:
          type: boolean
        requestSignatureUponDelivery:
          type: boolean
        isLocalCollect:
          type: boolean
        safePlace:
          type: string
          maxLength: 90
        department:
          type: string
          maxLength: 150
        AIRNumber:
          type: string
          maxLength: 50
        IOSSNumber:
          type: string
          maxLength: 50
        requiresExportLicense:
          type: boolean
        commercialInvoiceNumber:
          type: string
          maxLength: 35
        commercialInvoiceDate:
          type: string
          format: date-time
        recipientEoriNumber:
          type: string
    GetOrderDetailsResource:
      required:
      - subtotal
      - shippingCostCharged
      - orderDiscount
      - total
      - weightInGrams
      - shippingDetails
      - shippingInfo
      - billingInfo
      - orderLines
      type: object
      properties:
        orderIdentifier:
          type: integer
        orderStatus:
          type: string
        createdOn:
          type: string
          format: date-time
        printedOn:
          type: string
          format: date-time
        shippedOn:
          type: string
          format: date-time
        postageAppliedOn:
          type: string
          format: date-time
        manifestedOn:
          type: string
          format: date-time
        orderDate:
          type: string
          format: date-time
        despatchedByOtherCourierOn:
          type: string
          format: date-time
        tradingName:
          type: string
        channel:
          type: string
        marketplaceTypeName:
          type: string
        department:
          type: string
        AIRNumber:
          type: string
        requiresExportLicense:
          type: boolean
        commercialInvoiceNumber:
          type: string
        commercialInvoiceDate:
          type: string
          format: date-time
        orderReference:
          type: string
        channelShippingMethod:
          type: string
        specialInstructions:
          type: string
        pickerSpecialInstructions:
          type: string
        subtotal:
          type: number
        shippingCostCharged:
          type: number
        orderDiscount:
          type: number
        total:
          type: number
        weightInGrams:
          type: integer
        packageSize:
          type: string
        accountBatchNumber:
          type: string
        currencyCode:
          type: string
          maxLength: 3
        shippingDetails:
          $ref: '#/components/schemas/GetShippingDetailsResult'
        shippingInfo:
          $ref: '#/components/schemas/GetPostalDetailsResult'
        billingInfo:
          $ref: '#/components/schemas/GetPostalDetailsResult'
        orderLines:
          type: array
          items:
            $ref: '#/components/schemas/GetOrderLineResult'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/GetTagDetailsResult'
    CreateOrderResponse:
      required:
      - orderIdentifier
      - createdOn
      type: object
      properties:
        orderIdentifier:
          type: integer
        orderReference:
          type: string
        createdOn:
          type: string
          format: date-time
        orderDate:
          type: string
          format: date-time
        printedOn:
          type: string
          format: date-time
        manifestedOn:
          type: string
          format: date-time
        shippedOn:
          type: string
          format: date-time
        trackingNumber:
          type: string
        packages:
          type: array
          items:
            $ref: '#/components/schemas/CreatePackagesResponse'
        label:
          type: string
          description: label in format base64 string
        labelErrors:
          type: array
          items:
            $ref: '#/components/schemas/CreateOrderLabelErrorResponse'
        generatedDocuments:
          type: array
          items:
            type: string
    GetOrdersResponse:
      type: object
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/GetOrderInfoResource'
        continuationToken:
          type: string
    OrderErrorResponse:
      type: object
      properties:
        accountOrderNumber:
          type: integer
        channelOrderReference:
          type: string
        code:
          type: string
        message:
          type: string
    SenderDetailsRequest:
      type: object
      properties:
        tradingName:
          type: string
          maxLength: 250
        phoneNumber:
          maxLength: 25
          type: string
        emailAddress:
          maxLength: 254
          type: string
    DeleteOrdersResource:
      type: object
      properties:
        deletedOrders:
          type: array
          items:
            $ref: '#/components/schemas/DeletedOrderInfo'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/OrderErrorInfo'
    CreateOrdersResponse:
      type: object
      properties:
        successCount:
          type: integer
        errorsCount:
          type: integer
        createdOrders:
          type: array
          items:
            $ref: '#/components/schemas/CreateOrderResponse'
        failedOrders:
          type: array
          items:
            $ref: '#/components/schemas/FailedOrderResponse'
    GetOrderLineResult:
      required:
      - quantity
      type: object
      properties:
        SKU:
          type: string
        name:
          type: string
        quantity:
          type: integer
        unitValue:
          type: number
        lineTotal:
          type: number
        customsCode:
          type: string
    OrderErrorInfo:
      type: object
      properties:
        orderIdentifier:
          type: integer
        orderReference:
          type: string
        code:
          type: string
        message:
          type: string
    FailedOrderResponse:
      type: object
      properties:
        order:
          $ref: '#/components/schemas/CreateOrderRequest'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/CreateOrderErrorResponse'
    CreateOrdersRequest:
      required:
      - items
      type: object
      properties:
        items:
          minLength: 1
          type: array
          items:
            $ref: '#/components/schemas/CreateOrderRequest'
    AddressRequest:
      required:
      - addressLine1
      - city
      - countryCode
      type: object
      properties:
        fullName:
          maxLength: 210
          type: string
        companyName:
          maxLength: 100
          type: string
        addressLine1:
          maxLength: 100
          type: string
        addressLine2:
          maxLength: 100
          type: string
        addressLine3:
          maxLength: 100
          type: string
        city:
          maxLength: 100
          type: string
        county:
          maxLength: 100
          type: string
        postcode:
          maxLength: 20
          type: string
        countryCode:
          maxLength: 3
          type: string
    GetPostalDetailsResult:
      type: object
      properties:
        title:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        companyName:
          type: string
        addressLine1:
          type: string
        addressLine2:
          type: string
        addressLine3:
          type: string
        city:
          type: string
        county:
          type: string
        postcode:
          type: string
        countryCode:
          type: string
          maxLength: 3
        phoneNumber:
          type: string
        emailAddress:
          type: string
    TagRequest:
      type: object
      properties:
        key:
          type: string
          maxLength: 100
        value:
          type: string
          maxLength: 100
    UpdateOrdersStatusRequest:
      type: object
      properties:
        items:
          minLength: 1
          type: array
          items:
            $ref: '#/components/schemas/UpdateOrderStatusRequest'
    UpdateOrderStatusRequest:
      type: object
      properties:
        orderIdentifier:
          type: integer
          format: int32
        orderReference:
          type: string
        status:
          type: string
          enum:
          - new
          - despatchedByOtherCourier
          - despatched
        trackingNumber:
          type: string
        despatchDate:
          format: date-time
          type: string
        shippingCarrier:
          type: string
        shippingService:
          type: string
    LabelGenerationRequest:
      type: object
      description: Reserved for OBA customers only.
      required:
      - includeLabelInResponse
      properties:
        includeLabelInResponse:
          type: boolean
        includeCN:
          type: boolean
        includeReturnsLabel:
          type: boolean
  parameters:
    orderIdentifiers:
      in: path
      name: orderIdentifiers
      required: true
      description: One or several Order Identifiers or Order References separated by semicolon. The maximum number of identifiers is 100.
      schema:
        type: string
    continuationToken:
      in: query
      name: continuationToken
      required: false
      description: The token for retrieving the next page of items
      schema:
        type: string
    endDateTime:
      in: query
      name: endDateTime
      required: false
      description: Date and time upper bound for items filtering
      schema:
        type: string
        format: date-time
    startDateTime:
      in: query
      name: startDateTime
      required: false
      description: Date and time lower bound for items filtering
      schema:
        type: string
        format: date-time
    pageSize:
      in: query
      name: pageSize
      required: false
      description: The number of items to return
      schema:
        type: integer
        default: 25
        maximum: 100
        minimum: 1
  securitySchemes:
    Bearer:
      type: apiKey
      description: Authorization header using the Bearer scheme. Enter 'Bearer [space] and then your token.
      name: Authorization
      in: header