Sendle Orders API

openapi: 3.1.0
info:
  title: Sendle Shipping Manifests Orders API
  version: '1.0'
  description: 'Create and manage shipping manifests so a driver can collect multiple parcels

    by scanning a single barcode. Currently supports USPS SCAN Forms for US domestic

    orders only. Manifests can only include orders booked the same day.

    '
  contact:
    name: Sendle API Support
    email: api@sendle.com
    url: https://developers.sendle.com
servers:
- url: https://api.sendle.com/api
  description: Production
- url: https://sandbox.sendle.com/api
  description: Sandbox
security:
- basicAuth: []
tags:
- name: Orders
  description: Create, view, cancel, and return parcel orders
paths:
  /orders:
    post:
      operationId: createOrder
      summary: Create An Order
      tags:
      - Orders
      description: Creates an order to ship a parcel to the given delivery address.
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
            examples:
              domesticAU:
                $ref: '#/components/examples/DomesticAURequest'
              internationalAUNZ:
                $ref: '#/components/examples/InternationalAUNZRequest'
      responses:
        '201':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /orders/{id}:
    get:
      operationId: viewOrder
      summary: View An Order
      tags:
      - Orders
      description: Returns the order including its status, the public tracking URL, and the metadata you passed when creating it.
      parameters:
      - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          $ref: '#/components/responses/NotFound'
  /orders/{id}/cancel:
    post:
      operationId: cancelOrder
      summary: Cancel An Order
      tags:
      - Orders
      description: Cancels the given order if it has not yet been collected by a driver.
      parameters:
      - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: Cancellation result
          content:
            application/json:
              schema:
                type: object
                properties:
                  order_id:
                    type: string
                    format: uuid
                  state:
                    type: string
                    example: Cancelled
                  order_url:
                    type: string
                    format: uri
                  cancelled_at:
                    type: string
                    format: date-time
                  cancellable:
                    type: boolean
                  cancellation_message:
                    type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /orders/{id}/return:
    post:
      operationId: returnOrder
      summary: Return An Order
      tags:
      - Orders
      description: Creates a return label, letting receivers easily send orders back to the original sender. Domestic only.
      parameters:
      - $ref: '#/components/parameters/OrderId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_reference:
                  type: string
                  maxLength: 255
                receiver:
                  type: object
                  properties:
                    instructions:
                      type: string
                      maxLength: 200
      responses:
        '201':
          description: Return order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
    get:
      operationId: viewReturnOrder
      summary: View A Return Order
      tags:
      - Orders
      description: Views the given return order, including the label URLs.
      parameters:
      - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: Return order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Address:
      type: object
      required:
      - address_line1
      - suburb
      - postcode
      - state_name
      properties:
        address_line1:
          type: string
          maxLength: 255
        address_line2:
          type: string
          maxLength: 255
        suburb:
          type: string
        postcode:
          type: string
        state_name:
          type: string
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: AU
    Cover:
      type: object
      properties:
        total_cover:
          type: object
          properties:
            amount:
              type: number
        price:
          $ref: '#/components/schemas/Price'
    Weight:
      type: object
      required:
      - value
      - units
      properties:
        value:
          type: string
          description: Decimal string
        units:
          type: string
          enum:
          - kg
          - lb
          - g
          - oz
    Price:
      type: object
      properties:
        gross:
          $ref: '#/components/schemas/Money'
        net:
          $ref: '#/components/schemas/Money'
        tax:
          $ref: '#/components/schemas/Money'
    Money:
      type: object
      properties:
        amount:
          type: number
        currency:
          type: string
          enum:
          - AUD
          - CAD
          - USD
    OrderRequest:
      type: object
      required:
      - sender
      - receiver
      - description
      - weight
      - dimensions
      properties:
        sender:
          $ref: '#/components/schemas/Party'
        receiver:
          $ref: '#/components/schemas/Party'
        description:
          type: string
          maxLength: 255
        weight:
          $ref: '#/components/schemas/Weight'
        dimensions:
          $ref: '#/components/schemas/Dimensions'
        volume:
          $ref: '#/components/schemas/Volume'
        customer_reference:
          type: string
          maxLength: 255
        product_code:
          type: string
        first_mile_option:
          type: string
          enum:
          - pickup
          - drop off
          deprecated: true
        pickup_date:
          type: string
          format: date
        packaging_type:
          type: string
          enum:
          - box
          - satchel
          - unlimited satchel
        metadata:
          type: object
          additionalProperties: true
        hide_pickup_address:
          type: boolean
        cover:
          $ref: '#/components/schemas/Cover'
        parcel_contents:
          type: array
          items:
            $ref: '#/components/schemas/ParcelContent'
        contents_type:
          type: string
          enum:
          - Documents
          - Gift
          - Merchandise
          - Returned Goods
          - Sample
          - Other
    ParcelContent:
      type: object
      required:
      - description
      - value
      - country_of_origin
      - hs_code
      properties:
        description:
          type: string
          minLength: 3
          maxLength: 300
        value:
          type: string
          description: Decimal string >= 0.01
        quantity:
          type: integer
          default: 1
        country_of_origin:
          type: string
        hs_code:
          type: string
          pattern: ^[0-9]{4}\.[0-9]{2}(?:\.[0-9]{1,4})?$
        manufacturer_id:
          type: string
          maxLength: 15
    Dimensions:
      type: object
      required:
      - length
      - width
      - height
      - units
      properties:
        length:
          type: string
        width:
          type: string
        height:
          type: string
        units:
          type: string
          enum:
          - cm
          - in
    Error:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
        messages:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    Product:
      type: object
      properties:
        code:
          type: string
        name:
          type: string
        first_mile_option:
          type: string
          enum:
          - pickup
          - drop off
        service:
          type: string
          enum:
          - standard
          - express
        atl_only:
          type: boolean
    Contact:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        phone:
          type: string
        email:
          type: string
          format: email
        company:
          type: string
        sendle_id:
          type: string
    Scheduling:
      type: object
      properties:
        is_cancellable:
          type: boolean
        pickup_date:
          type: string
          format: date
          nullable: true
        picked_up_on:
          type: string
          format: date
          nullable: true
        delivered_on:
          type: string
          format: date
          nullable: true
        estimated_delivery_date_minimum:
          type: string
          format: date
          nullable: true
        estimated_delivery_date_maximum:
          type: string
          format: date
          nullable: true
    Party:
      type: object
      properties:
        contact:
          $ref: '#/components/schemas/Contact'
        address:
          $ref: '#/components/schemas/Address'
        instructions:
          type: string
          maxLength: 200
        tax_ids:
          type: object
          properties:
            ioss:
              type: string
              pattern: ^IM[0-9]{10}$
    Order:
      type: object
      properties:
        order_id:
          type: string
          format: uuid
        state:
          type: string
        order_url:
          type: string
          format: uri
        sendle_reference:
          type: string
          minLength: 6
        tracking_url:
          type: string
          format: uri
        metadata:
          type: object
          additionalProperties: true
        labels:
          type: array
          items:
            type: object
            properties:
              format:
                type: string
                enum:
                - pdf
                - png
              size:
                type: string
                enum:
                - cropped
                - a4
                - letter
              url:
                type: string
                format: uri
        scheduling:
          $ref: '#/components/schemas/Scheduling'
        hide_pickup_address:
          type: boolean
        description:
          type: string
        weight:
          $ref: '#/components/schemas/Weight'
        volume:
          $ref: '#/components/schemas/Volume'
        dimensions:
          $ref: '#/components/schemas/Dimensions'
        customer_reference:
          type: string
        sender:
          $ref: '#/components/schemas/Party'
        receiver:
          $ref: '#/components/schemas/Party'
        route:
          $ref: '#/components/schemas/Route'
        price:
          $ref: '#/components/schemas/Price'
        price_breakdown:
          type: object
          additionalProperties: true
        tax_breakdown:
          type: object
          additionalProperties: true
        cover:
          $ref: '#/components/schemas/Cover'
        packaging_type:
          type: string
          enum:
          - box
          - satchel
          - unlimited satchel
        parcel_contents:
          type: array
          items:
            $ref: '#/components/schemas/ParcelContent'
        contents_type:
          type: string
          enum:
          - Documents
          - Gift
          - Merchandise
          - Returned Goods
          - Sample
          - Other
        product:
          $ref: '#/components/schemas/Product'
        expires_at:
          type: string
          format: date-time
    Volume:
      type: object
      properties:
        value:
          type: string
        units:
          type: string
          enum:
          - l
          - m3
          - in3
          - ft3
    Route:
      type: object
      properties:
        description:
          type: string
        type:
          type: string
          enum:
          - same-city
          - national
          - remote
          - export
        delivery_guarantee_status:
          type: string
          enum:
          - eligible
          - ineligible
  parameters:
    OrderId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: The order_id UUID returned from createOrder.
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 100
      description: Client-provided key to make order creation idempotent.
  responses:
    UnprocessableEntity:
      description: Validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Malformed request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  examples:
    DomesticAURequest:
      summary: Domestic AU pickup
      value:
        sender:
          contact:
            name: Lex Luthor
            phone: 0491 570 313
            email: lluthor@example.com
            company: LexCorp
          address:
            address_line1: 123 Gotham Ln
            suburb: Sydney
            state_name: NSW
            postcode: '2000'
            country: AU
          instructions: Knock loudly
        receiver:
          contact:
            name: Clark Kent
            email: clarkissuper@dailyplanet.xyz
            company: Daily Planet
          address:
            address_line1: 80 Wentworth Park Road
            suburb: Glebe
            state_name: NSW
            postcode: '2037'
            country: AU
          instructions: Give directly to Clark
        description: Kryptonite
        weight:
          value: '1.0'
          units: kg
        dimensions:
          length: '30.0'
          width: '20.0'
          height: '17.0'
          units: cm
        customer_reference: SupBdayPressie
        metadata:
          your_data: XYZ123
        hide_pickup_address: true
        packaging_type: box
    InternationalAUNZRequest:
      summary: International AU to NZ
      value:
        sender:
          contact:
            name: Lex Luthor
            phone: 0491 570 313
            email: lluthor@example.com
          address:
            address_line1: 123 Gotham Ln
            suburb: Sydney
            state_name: NSW
            postcode: '2000'
            country: AU
        receiver:
          contact:
            name: Clark Kent
            phone: +64 21 555 1234
            email: clarkissuper@dailyplanet.xyz
          address:
            address_line1: 1 Queen St
            suburb: Auckland
            state_name: AUK
            postcode: '1010'
            country: NZ
          instructions: Please leave at door
        description: Kryptonite
        weight:
          value: '1.0'
          units: kg
        dimensions:
          length: '30.0'
          width: '20.0'
          height: '17.0'
          units: cm
        parcel_contents:
        - description: Kryptonite mineral sample
          value: '900.0'
          quantity: 1
          country_of_origin: US
          hs_code: 2530.10.00
        contents_type: Gift
        packaging_type: box
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic