> ## Documentation Index
> Fetch the complete documentation index at: https://sendcloud.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve a list of orders

> Get a list of orders filtered by integration, order number, order ID, order status, creation date, and update date. You can also optionally sort the results and pass a `cursor` value.

This endpoint lets you get a list of orders from the API in the same way you can find it on the Incoming Orders overview in the Sendcloud platform.

The endpoint is paginated. You can navigate through the results by using the URLs of the `next` and `prev` fields in the `Link` response header.


## OpenAPI

````yaml /.openapi/v3/orders/openapi.yaml get /orders
openapi: 3.1.0
info:
  title: Orders
  version: 3.0.0
  contact:
    name: Sendcloud API Support
    email: contact@sendcloud.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  description: >-
    The Orders API lets you manage your orders within Sendcloud. You can create
    and update orders in batch, retrieve a list of orders per integration,
    retrieve an order, partially update an order, and delete an order.
servers:
  - url: https://panel.sendcloud.sc/api/v3
    description: Sendcloud Production
security: []
tags:
  - name: Orders
    description: OrderAPI
paths:
  /orders:
    get:
      tags:
        - Orders
      summary: Retrieve a list of orders
      description: >-
        Get a list of orders filtered by integration, order number, order ID,
        order status, creation date, and update date. You can also optionally
        sort the results and pass a `cursor` value.
      operationId: sc-public-v3-orders-get-list_orders
      parameters:
        - $ref: '#/components/parameters/integration'
        - $ref: '#/components/parameters/order_number'
        - $ref: '#/components/parameters/order_id'
        - $ref: '#/components/parameters/order_status'
        - $ref: '#/components/parameters/order_created_at'
        - $ref: '#/components/parameters/order_created_at_min'
        - $ref: '#/components/parameters/order_created_at_max'
        - $ref: '#/components/parameters/order_updated_at'
        - $ref: '#/components/parameters/order_updated_at_min'
        - $ref: '#/components/parameters/order_updated_at_max'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/page_size'
        - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: OK
          headers:
            Link:
              description: >-
                Links to related resources in the [RFC
                5988](https://tools.ietf.org/html/rfc5988#section-5) format.
                This includes the links with the `next` and `prev` types for the
                next and the previous pages.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/order'
              examples:
                Response:
                  value:
                    data:
                      - id: '669'
                        order_id: '555413'
                        order_number: OXSDFGHTD-12
                        created_at: '2018-02-27T10:00:00.555Z'
                        modified_at: '2018-02-27T10:00:00.555Z'
                        order_details:
                          integration:
                            id: 739283
                          status:
                            code: fulfilled
                            message: Fulfilled
                          order_created_at: '2018-02-27T10:00:00.555Z'
                          order_updated_at: '2018-02-27T10:00:00.555Z'
                          order_items:
                            - name: Cylinder candle
                              measurement:
                                weight:
                                  value: 1
                                  unit: kg
                              quantity: 1
                              unit_price:
                                value: 3.5
                                currency: EUR
                              total_price:
                                value: 3.5
                                currency: EUR
                              delivery_dates:
                                handover_at: '2022-02-27T10:00:00.555309+00:00'
                                deliver_at: '2022-03-02T11:50:00.555309+00:00'
                              mid_code: US1234567
                              material_content: 100% Cotton
                              intended_use: Personal use
                        payment_details:
                          is_cash_on_delivery: false
                          total_price:
                            value: 7
                            currency: EUR
                          status:
                            code: paid
                            message: Order has been paid
                          discount_granted:
                            value: '3.99'
                            currency: EUR
                          insurance_costs:
                            value: '9.99'
                            currency: EUR
                          freight_costs:
                            value: '5.99'
                            currency: EUR
                          other_costs:
                            value: '2.99'
                            currency: EUR
                        customs_details:
                          commercial_invoice_number: 0124-03102022
                          shipment_type: commercial_goods
                          export_type: commercial_b2c
                          tax_numbers:
                            sender:
                              - name: VAT
                                country_code: NL
                                value: NL987654321B02
                            receiver:
                              - name: VAT
                                country_code: DE
                                value: DE123456789B03
                            importer_of_record:
                              - name: VAT
                                country_code: NL
                                value: NL975318642B01
                        shipping_address:
                          name: John Doe
                          address_line_1: Stadhuisplein
                          house_number: '15'
                          postal_code: 5341TW
                          city: Oss
                          country_code: NL
                        shipping_details:
                          is_local_pickup: false
                          ship_with:
                            type: shipping_option_code
                            properties:
                              shipping_option_code: postnl:standard
                              contract_id: 517
                        billing_address:
                          name: Jane Doe
                          address_line_1: Vioolstraat
                          house_number: '118'
                          postal_code: 5391TW
                          city: Breda
                          country_code: NL
                        customer_details:
                          name: Jane Doe
                      - id: '1337'
                        order_id: '555414'
                        created_at: '2018-03-21T10:00:00.555Z'
                        modified_at: '2018-03-22T10:00:00.555Z'
                        order_number: OXSDFGHTD-13
                        order_details:
                          integration:
                            id: 739283
                          status:
                            code: fulfilled
                            message: Fulfilled
                          order_created_at: '2018-02-27T10:00:00.555Z'
                          order_updated_at: '2018-02-28T11:05:15.634Z'
                          order_items:
                            - name: Squared Candle
                              measurement:
                                weight:
                                  value: 0.8
                                  unit: kg
                              quantity: 3
                              unit_price:
                                value: 2
                                currency: EUR
                              total_price:
                                value: 6
                                currency: EUR
                              delivery_dates: null
                              mid_code: US1234567
                              material_content: 100% Cotton
                              intended_use: Personal use
                            - name: Scented Candle
                              quantity: 2
                              unit_price:
                                value: 5.5
                                currency: EUR
                              total_price:
                                value: 11
                                currency: EUR
                              delivery_dates: null
                              mid_code: US1234567
                              material_content: 100% Cotton
                              intended_use: Personal use
                        payment_details:
                          is_cash_on_delivery: false
                          total_price:
                            value: 7
                            currency: EUR
                          status:
                            code: paid
                            message: Order has been paid
                          discount_granted:
                            value: '3.99'
                            currency: EUR
                          insurance_costs:
                            value: '9.99'
                            currency: EUR
                          freight_costs:
                            value: '5.99'
                            currency: EUR
                          other_costs:
                            value: '2.99'
                            currency: EUR
                        customs_details:
                          commercial_invoice_number: 0124-03102022
                          shipment_type: commercial_goods
                          export_type: commercial_b2c
                          tax_numbers:
                            sender:
                              - name: VAT
                                country_code: NL
                                value: NL987654321B02
                            receiver:
                              - name: VAT
                                country_code: DE
                                value: DE123456789B03
                            importer_of_record:
                              - name: VAT
                                country_code: NL
                                value: NL975318642B01
                        shipping_address:
                          name: John Doe
                          address_line_1: Stadhuisplein
                          house_number: '15'
                          postal_code: 5341AB
                          city: Oss
                          country_code: NL
                          phone_number: '0612345678'
                        shipping_details:
                          is_local_pickup: false
                          ship_with:
                            type: shipping_option_code
                            properties:
                              shipping_option_code: postnl:standard
                              contract_id: 517
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
              examples:
                FilteringANonValidIntegration:
                  value:
                    errors:
                      - status: '400'
                        code: invalid_choice
                        title: Invalid Choice
                        detail: >-
                          Select a valid choice. 128 is not one of the available
                          choices.
                        source:
                          parameter: integration
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
              examples:
                FilteringNonExistingCursor:
                  value:
                    errors:
                      - status: '404'
                        title: Invalid cursor
                        code: not_found
                        detail: Invalid cursor
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds: []
components:
  parameters:
    integration:
      in: query
      name: integration
      description: >-
        Filter orders by one or more integration IDs. Use a comma separated
        list, e.g. `integration=41,68,419`.


        You can get your integration IDs from the [Retrieve a list of
        integrations](/api/v3/integrations/retrieve-a-list-of-integrations)
        endpoint.
      schema:
        type: integer
        example: 17
    order_number:
      in: query
      name: order_number
      description: >-
        Filter orders by a specific order number, e.g.
        `order_number=ORDER_284565`. The filtering is case insensitive.
      schema:
        type: string
        example: ORDER_284565
    order_id:
      in: query
      name: order_id
      description: >-
        Filter orders by a specific order id, e.g.
        `order_id=1896e94b-c01b-4e73-a9e7-57f51c8a4c77`. The filtering is case
        insensitive.
      schema:
        type: string
        example: 1896e94b-c01b-4e73-a9e7-57f51c8a4c77
    order_status:
      in: query
      name: status
      description: >-
        Filter orders based on their status, e.g. `status=unshipped`. The
        filtering is case insensitive.
      schema:
        type: string
        example: unshipped
    order_created_at:
      in: query
      name: order_created_at
      description: >-
        Find orders that were created on a specific date, e.g.
        `order_created_at=2023-04-28`.
      schema:
        type: string
        format: date
        example: '2023-04-28'
    order_created_at_min:
      in: query
      name: order_created_at_min
      description: >-
        Find orders that were created at or after a specific date, e.g.
        `order_created_at_min=2023-04-28`.
      schema:
        type: string
        format: date
        example: '2023-04-28'
    order_created_at_max:
      in: query
      name: order_created_at_max
      description: >-
        Find orders that were created at or before a specific date, e.g.
        `order_created_at_max=2023-04-28`.
      schema:
        type: string
        format: date
        example: '2023-04-28'
    order_updated_at:
      in: query
      name: order_updated_at
      description: >-
        Find orders that were updated on a specific date, e.g.
        `order_updated_at=2023-04-28`.
      schema:
        type: string
        format: date
        example: '2023-04-28'
    order_updated_at_min:
      in: query
      name: order_updated_at_min
      description: >-
        Find orders that were updated at or after a specific date, e.g.
        `order_updated_at_min=2023-04-28`.
      schema:
        type: string
        format: date
        example: '2023-04-28'
    order_updated_at_max:
      in: query
      name: order_updated_at_max
      description: >-
        Find orders that were updated at or before a specific date, e.g.
        `order_updated_at_max=2023-04-28`.
      schema:
        type: string
        format: date
        example: '2023-04-28'
    sort:
      in: query
      name: sort
      description: >-
        Sort the orders in the response by using one or more of the following
        values:
         - `integration`: Sort by the integration ID of the retrieved orders; to sort in descending order, use `-integration`
         - `order_number`: Sort by the order number of the retrieved orders; to sort in descending order, use `-order_number`.
         - `order_created_at`: Sort by the date of an order creation of the retrieved orders; to sort in descending order, use `-order_created_at`
         - `order_updated_at`: Sort by the date of an order update of the retrieved orders; to sort in descending order, use `-order_updated_at`
         - `pk`: Sort by the ID (autogenerated internal ID) of the retrieved orders; to sort in descending order, use `-pk`

        Additional information about this query:
         - Any valid combination of the above values is supported, e.g. `sort=integration,-order_created_at`. 
         - In case of conflicting `sort` values, e.g. `/?sort=integration,-integration`, the conflicting value will be ignored.
         - If the `sort` query parameter is not set, the sorting of the retrieved orders will default to `-pk`.
         - If an unsupported `sort` value is provided, the results will be sorted by the default (`-pk`).
      schema:
        type: string
        example: '-order_number'
    page_size:
      in: query
      name: page_size
      schema:
        type: number
        default: 100
        maximum: 200
        minimum: 1
        example: 150
      description: The maximum number of results to be returned per page
    cursor:
      in: query
      name: cursor
      description: >-
        The cursor query string is used as the pivot value to filter results. If
        no value is provided, the first page of results will be returned. To get
        this value, you must encode the offset, reverse and position into a
        base64 string.


        There are 3 possible parameters to encode:
          - `o`: Offset
          - `r`: Reverse
          - `p`: Position
          
        For example, `r=1&p=300` encoded as a base64 string would be
        `cj0xJnA9MzAw`. The query string would then be `cursor=cj0xJnA9MzAw`.
      schema:
        type: string
        example: cj0xJnA9MzAw
  schemas:
    order:
      title: Order Object
      type: object
      description: Sendcloud Order object
      properties:
        id:
          description: Autogenerated Sendcloud's internal ID
          type: string
          readOnly: true
        order_id:
          type: string
          description: External order ID assigned by shop system
          example: 7bdd5bfd-76bc-4654-9d40-5d5d49f1cd6c
          minLength: 1
        order_number:
          type: string
          description: Unique order number generated manually or by shop system
          example: '101170081'
          minLength: 1
        created_at:
          type: string
          format: date-time
          description: The date when an order was created at Sendcloud in ISO 8601
          example: '2018-02-27T10:00:00.555309+00:00'
          readOnly: true
        modified_at:
          type: string
          format: date-time
          description: The date when an order was last modified at Sendcloud in ISO 8601
          example: '2018-02-27T10:00:00.555309+00:00'
          readOnly: true
        order_details:
          type: object
          description: Node for general order information
          required:
            - integration
            - status
            - order_created_at
            - order_items
          properties:
            integration:
              type: object
              description: Sendcloud Integration object where orders come from
              required:
                - id
              properties:
                id:
                  type: integer
                  description: >-
                    Sendcloud Integration ID. To obtain the integration ID, you
                    can use the [Retrieve a list of
                    integrations](/api/v3/integrations/retrieve-a-list-of-integrations)
                    endpoint.
                  example: 7
            status:
              type: object
              description: Order status
              required:
                - code
              properties:
                code:
                  type: string
                  description: Custom internal shop status, you can use it for filtering
                  example: fulfilled
                  minLength: 1
                message:
                  type: string
                  description: User-defined human readable status
                  example: Order has been fulfilled
            order_created_at:
              type: string
              format: date-time
              description: >-
                The date and time that the order was placed in the respective
                shop system in ISO 8601
              example: '2018-02-27T10:00:00.555309+00:00'
            order_updated_at:
              type: string
              format: date-time
              description: >-
                The date and time that the order was last updated in the
                respective shop system in ISO 8601
              example: '2018-02-27T10:00:00.555309+00:00'
            order_items:
              $ref: '#/components/schemas/order-items'
            notes:
              type: string
              description: Internal notes or comments placed by consumer on the order
              example: 'Call this number before delivery: 063 874 6473'
            tags:
              type: array
              description: Tags assigned to the order
              items:
                type: string
              example:
                - fragile
                - countryside warehouse
        payment_details:
          $ref: '#/components/schemas/payment-details'
        customs_details:
          $ref: '#/components/schemas/customs-details'
        customer_details:
          $ref: '#/components/schemas/customer-details'
        billing_address:
          $ref: '#/components/schemas/billing-address'
        shipping_address:
          $ref: '#/components/schemas/shipping-address'
        shipping_details:
          $ref: '#/components/schemas/shipping-details'
        service_point_details:
          $ref: '#/components/schemas/service-point'
      required:
        - order_id
        - order_number
        - order_details
        - payment_details
    errors:
      title: Errors
      type: object
      description: A standardized format for errors in JSON:API responses.
      properties:
        errors:
          type:
            - array
            - object
          items:
            type: object
            allOf:
              - $ref: '#/components/schemas/ErrorObject'
            required:
              - status
              - code
              - detail
    order-items:
      title: Order Items
      type: array
      description: The list of items that an order contains
      items:
        type: object
        description: Order item
        properties:
          item_id:
            type: string
            description: Order Item external ID in shop system
            example: '5552'
            minLength: 1
          product_id:
            type: string
            description: Shop system product ID
            example: '1458734634'
          variant_id:
            type: string
            description: Shop system variant ID of the product
            example: '15346645'
          image_url:
            type: string
            description: >-
              A url to an image representing the given product (or variation of
              the product if applicable). When providing `image_url` the
              `product_id` is required for image to be correctly displayed.
            format: url
            example: https://i.ibb.co/6tLZ2Jz/orange.jpeg
          name:
            type: string
            description: The name of ordered product
            example: Cylinder candle
          description:
            type: string
            description: The product description
            example: Pebble green - 12x8 cm
          quantity:
            type: integer
            description: >-
              The quantity field on an order item represents the number of units
              of a product a customer has ordered.
            example: 2
            minLength: 1
          sku:
            type: string
            example: WW-DR-GR-XS-001
            description: >-
              Stock keeping unit - used by retailers to assign to products, in
              order to keep track of stock levels internally.
          hs_code:
            type: string
            description: >-
              The Harmonized System (HS) code is a standardized numerical system
              used to classify traded products in international commerce
            example: '6205.20'
          country_of_origin:
            type: string
            example: NL
            description: Country code of origin of the item in ISO 3166-1 alpha-2
            maxLength: 2
            minLength: 2
          properties:
            type: object
            additionalProperties: true
            description: Any custom user-defined properties of order item or product
            example:
              size: red
              color: green
          unit_price:
            $ref: '#/components/schemas/price'
            description: >
              The price of a single item in the shop’s currency before discounts
              have been applied.

              - **[Sendcloud platform mapping]** This value is shown directly in
              the Unit value field in the Sendcloud platform.
          total_price:
            $ref: '#/components/schemas/price'
            description: >
              The total price for this item line, after any item-level
              discounts, in the shop’s currency.

              - It should reflect `unit_price × quantity`, minus discounts (if
              applicable).

              - **[Sendcloud platform mapping]** Not displayed in the Sendcloud
              platform. Instead, the Sendcloud platform calculates its own total
              as `unit_price × quantity`.
          measurement:
            $ref: '#/components/schemas/measurement'
          ean:
            type: string
            description: European standardised number for an article, EAN-13
            example: '0799439112766'
          delivery_dates:
            $ref: '#/components/schemas/delivery-dates'
          mid_code:
            title: MID Code
            type:
              - string
              - 'null'
            description: >-
              MID code is short for Manufacturer's Identification code and must
              be shown on the commercial invoice. It's used as an alternative to
              the full name and address of a manufacturer, shipper or exporter
              and is always required for U.S. formal customs entries.
            example: NLOZR92MEL
          material_content:
            title: Material Content
            type:
              - string
              - 'null'
            description: A description of materials of the order content.
            example: 100% Cotton
          intended_use:
            title: Intended Use
            type:
              - string
              - 'null'
            description: >-
              Intended use of the order contents. The intended use may be
              personal or commercial.
            example: Personal use
          dangerous_goods:
            $ref: '#/components/schemas/dangerous-goods'
        required:
          - name
          - quantity
          - total_price
    payment-details:
      title: Payment Details
      type: object
      description: Node for everything about payments and money
      required:
        - total_price
        - status
      properties:
        is_cash_on_delivery:
          type:
            - boolean
            - 'null'
          description: >-
            Indicates if customers will pay the full order amount upon delivery
            of the order
          example: true
        total_price:
          oneOf:
            - $ref: '#/components/schemas/price'
          description: Total value in the shop currency
          required:
            - value
            - currency
        subtotal_price:
          oneOf:
            - $ref: '#/components/schemas/price'
          description: Subtotal value in the shop currency
          required:
            - value
            - currency
        estimated_shipping_price:
          oneOf:
            - $ref: '#/components/schemas/price'
          description: Sum of all shipping costs
          required:
            - value
            - currency
        estimated_tax_price:
          oneOf:
            - $ref: '#/components/schemas/price'
          description: Sum of all estimated taxes for the order
          required:
            - value
            - currency
        status:
          type: object
          description: Payment status of an order
          required:
            - code
          properties:
            code:
              type: string
              description: Custom internal shop status, you can use it for filtering
              example: paid
              minLength: 1
            message:
              type: string
              description: User-defined human readable status
              example: Order has been paid
        invoice_date:
          type:
            - string
            - 'null'
          title: Invoice Date
          description: The date when invoice was issued.
          example: '2018-07-14'
        discount_granted:
          $ref: '#/components/schemas/costs-object'
          type:
            - object
            - 'null'
          title: Discount Granted
          description: >-
            Discount granted on the total order excluding any possible discounts
            on shipping.
        insurance_costs:
          $ref: '#/components/schemas/costs-object'
          type:
            - object
            - 'null'
          title: Insurance Cost
          description: Amount the order is insured for
        freight_costs:
          $ref: '#/components/schemas/costs-object'
          type:
            - object
            - 'null'
          title: Freight Cost
          description: Shipping cost of the order after discounts have been applied.
        other_costs:
          $ref: '#/components/schemas/costs-object'
          type:
            - object
            - 'null'
          title: Other Costs
          description: Any other costs (for eg, wrapping costs) associated with the order
    customs-details:
      title: Customs Details
      type:
        - object
        - 'null'
      description: Customs information required for international shipments.
      properties:
        commercial_invoice_number:
          type: string
          description: Your own commercial invoice number
          example: '1002404102022'
        shipment_type:
          type: string
          description: >-
            Indicates the purpose or reason behind exporting the items. This
            classification helps customs authorities determine the applicable
            regulations, taxes, and duties.
          enum:
            - gift
            - commercial_goods
            - commercial_sample
            - returned_goods
          example: commercial_goods
        export_type:
          type: string
          description: >
            Export type documentation serves to categorize international
            shipments into three primary classifications: 
              - Private exports, intended for personal use
              - Commercial B2C exports, directed towards individual consumers
              - Commercial B2B exports, involving business-to-business transactions
              These distinctions facilitate adherence to regulatory requirements and ensure the orderly movement of goods across international boundaries.
          enum:
            - private
            - commercial_b2c
            - commercial_b2b
          example: private
        tax_numbers:
          type:
            - object
            - 'null'
          title: >-
            Identification numbers and codes related to sender, receiver and
            importer of record provider.
          properties:
            sender:
              type: array
              title: Sender's Tax Information
              minItems: 0
              items:
                $ref: '#/components/schemas/tax-number'
            receiver:
              type: array
              title: Receiver's Tax Information
              minItems: 0
              items:
                $ref: '#/components/schemas/tax-number'
            importer_of_record:
              type: array
              title: Receiver's Tax Information
              minItems: 0
              items:
                $ref: '#/components/schemas/tax-number'
    customer-details:
      title: Customer Details
      type: object
      description: Node for an information about customer
      properties:
        name:
          type: string
          description: Name of the customer
          example: John Doe
        phone_number:
          type: string
          description: Phone number of the customer
          example: '+319881729999'
        email:
          type: string
          description: Email of the customer
          example: john@doe.com
      required:
        - name
    billing-address:
      title: Billing Address
      oneOf:
        - $ref: '#/components/schemas/address'
      required:
        - name
        - address_line_1
        - postal_code
        - city
        - country_code
      description: Sendcloud Billing Address object
    shipping-address:
      title: Shipping Address
      oneOf:
        - $ref: '#/components/schemas/address'
      required:
        - name
        - address_line_1
        - postal_code
        - city
        - country_code
      description: Sendcloud Shipping Address object
    shipping-details:
      type: object
      description: Shipping information
      properties:
        is_local_pickup:
          type:
            - boolean
            - 'null'
          description: >-
            Indicates if customers should collect the order in person from a
            merchant location
          example: true
        delivery_indicator:
          title: Delivery Indicator
          description: >-
            A free text field to indicate how a specific order should be
            shipped.


            - The field is intended for applying the Checkout Delivery Method
            condition in shipping rules.

            - Learn more about [shipping rules](/docs/shipping/shipping-rules/).
          type: string
          example: DHL Home Delivery
        measurement:
          $ref: '#/components/schemas/measurement'
          description: Total order measurements
        ship_with:
          $ref: '#/components/schemas/ship-with'
    service-point:
      title: Service Point
      type: object
      description: >-
        Node for service point information. The service point information can be
        retrieved from the [Service points API](/api/v2/service-points).


        You must provide either the Sendcloud `id` or the
        `carrier_service_point_id` to identify the service point.
      oneOf:
        - title: Sendcloud ID
          type: object
          properties:
            id:
              type: string
              description: >-
                An id of Sendcloud Service Point to which the shipment is going
                to be shipped
              example: '123'
            post_number:
              type: string
              description: >-
                An optional field that only applies to PackStation service point
                types
              example: some-post-number
            latitude:
              type: string
              description: The Latitude of where the service point is located
              example: '51.427063'
            longitude:
              type: string
              description: The Longitude of where the service point is located
              example: '5.486414'
            type:
              type: string
              description: Carrier defined service point type
              example: packstation
            extra_data:
              type: object
              additionalProperties: true
              description: Can contain carrier specific data
          required:
            - id
        - title: Carrier Service Point ID
          type: object
          properties:
            carrier_service_point_id:
              type: string
              description: The carrier's native id for the service point
              example: '91233'
            post_number:
              type: string
              description: >-
                An optional field that only applies to PackStation service point
                types
              example: some-post-number
            latitude:
              type: string
              description: The Latitude of where the service point is located
              example: '51.427063'
            longitude:
              type: string
              description: The Longitude of where the service point is located
              example: '5.486414'
            type:
              type: string
              description: Carrier defined service point type
              example: packstation
            extra_data:
              type: object
              additionalProperties: true
              description: Can contain carrier specific data
          required:
            - carrier_service_point_id
    ErrorObject:
      title: Error
      type: object
      description: Error in a JSON:API error format
      properties:
        id:
          type: string
          description: A unique identifier for the error.
        links:
          type: object
          description: >-
            A set of hyperlinks that provide additional information about the
            error.
          properties:
            about:
              type: string
              description: A URL that provides additional information about the error.
        status:
          type: string
          format: int32
          description: The HTTP status code of the error.
          minLength: 1
        code:
          type: string
          description: A unique error code for the error, in snake case format.
          minLength: 1
          enum:
            - unknown_field
            - invalid
            - forbidden
            - invalid_choice
            - min_value
            - 'null'
            - not_found
            - required
            - not_a_list
            - non_field_errors
            - authentication_failed
            - validation_error
            - parcel_announcement_error
        title:
          type: string
          description: A short, human-readable summary of the error.
          minLength: 1
        detail:
          type: string
          description: A human-readable explanation of the error.
          minLength: 1
        source:
          type: object
          description: >-
            An object that identifies the source of the error within the request
            payload.
          properties:
            pointer:
              type: string
              description: >-
                A `JSON` pointer to the location of the error within the request
                payload.
            parameter:
              type: string
              description: The name of the `query` parameter that caused the error.
            header:
              type: string
              description: The name of the `header` parameter that caused the error.
        meta:
          type: object
          description: Additional metadata about the error.
    price:
      title: Price Object
      type: object
      properties:
        value:
          type: number
        currency:
          type: string
          description: ISO 4217 currency code
          enum:
            - EUR
            - GBP
            - USD
      description: Price in the specified currency
    measurement:
      title: Measurement Object
      type: object
      properties:
        dimension:
          $ref: '#/components/schemas/dimension'
        weight:
          $ref: '#/components/schemas/weight'
        volume:
          $ref: '#/components/schemas/volume'
      description: >-
        This object provides essential information for accurate packing,
        shipping, and inventory management
    delivery-dates:
      title: Delivery Dates
      description: Defined delivery dates
      type:
        - object
      properties:
        handover_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            The date when the item will be handed over to the carrier by the
            merchant in ISO 8601
          example: '2025-02-27T10:00:00.555309+00:00'
        deliver_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The date when the order should reach the end customer in ISO 8601
          example: '2025-03-15T10:00:00.555309+00:00'
    dangerous-goods:
      title: DangerousGoods
      type: object
      description: Hazardous materials information for items.
      properties:
        chemical_record_identifier:
          type: string
          nullable: true
          description: Chemical record identifier for the dangerous goods
        regulation_set:
          type: string
          enum:
            - IATA
            - ADR
          description: Regulation set governing the dangerous goods
        packaging_type_quantity:
          type: string
          nullable: true
          description: Quantity of packaging type
        packaging_type:
          type: string
          nullable: true
          description: Type of packaging used
        packaging_instruction_code:
          type: string
          nullable: true
          description: Packaging instruction code
        id_number:
          type: string
          nullable: true
          description: UN identification number
        class_division_number:
          type: string
          nullable: true
          description: Hazard class and division number
        quantity:
          type: string
          nullable: true
          description: Quantity of dangerous goods
        unit_of_measurement:
          type: string
          enum:
            - KG
            - G
            - L
            - ML
          description: Unit of measurement for dangerous goods quantity
        proper_shipping_name:
          type: string
          nullable: true
          description: Proper shipping name as defined by regulations
        commodity_regulated_level_code:
          type: string
          enum:
            - LQ
            - EQ
          description: Commodity regulated level code
        transportation_mode:
          type: string
          enum:
            - Highway
            - Ground
            - PAX
            - CAO
          description: Mode of transportation
        emergency_contact_name:
          type: string
          nullable: true
          description: Name of emergency contact person
        emergency_contact_phone:
          type: string
          nullable: true
          description: Phone number of emergency contact
        adr_packing_group_letter:
          type: string
          enum:
            - I
            - II
            - III
          description: ADR packing group classification
        local_proper_shipping_name:
          type: string
          nullable: true
          description: Local proper shipping name
        transport_category:
          type: string
          nullable: true
          description: Transport category for ADR regulations
        tunnel_restriction_code:
          type: string
          nullable: true
          description: Tunnel restriction code
        weight_type:
          type: string
          enum:
            - Net
            - Gross
          description: Type of weight measurement
    costs-object:
      title: Costs Object
      type: object
      properties:
        value:
          type:
            - string
            - 'null'
          pattern: '[\d]+(\.[\d]+)?'
          example: '3.99'
        currency:
          type:
            - string
            - 'null'
          example: EUR
    tax-number:
      title: Tax Number
      type: object
      properties:
        name:
          type:
            - string
            - 'null'
          title: Tax ID name
          example: VAT
        country_code:
          type:
            - string
            - 'null'
          title: The country code of the country in the address
          example: NL
        value:
          type:
            - string
            - 'null'
          title: The value of the Tax ID
          example: NL987654321B02
    address:
      title: Address Object
      type: object
      description: Sendcloud Address object
      properties:
        name:
          type: string
          example: John Doe
          description: Name of the person associated with the address
          minLength: 1
        company_name:
          type: string
          example: Sendcloud
          description: Name of the company associated with the address
        address_line_1:
          type: string
          example: Stadhuisplein
          description: First line of the address
        house_number:
          type: string
          example: '50'
          description: House number of the address
        address_line_2:
          type: string
          description: Additional address information, e.g. 2nd level
          example: Apartment 17B
        postal_code:
          type: string
          example: 1013 AB
          description: Zip code of the address
          minLength: 1
        city:
          type: string
          example: Eindhoven
          description: City of the address
          minLength: 1
        po_box:
          type:
            - string
            - 'null'
          description: Code required in case of PO Box or post locker delivery
        state_province_code:
          type: string
          example: IT-RM
          description: >-
            The character state code of the customer represented as ISO 3166-2
            code. This field is required for certain countries. See
            [international
            shipping](/docs/shipments/international-shipping#required-fields-for-international-shipments)
            for details.
        country_code:
          type: string
          example: NL
          description: The country code of the customer represented as ISO 3166-1 alpha-2
          minLength: 1
        email:
          type: string
          format: email
          example: johndoe@gmail.com
          description: Email address of the person associated with the address
        phone_number:
          type: string
          example: '+319881729999'
          description: Phone number of the person associated with the address
    ship-with:
      title: Ship with object
      type: object
      description: >
        The ship with object can be used to define how you would like to send
        your shipment.


        You can use a `shipping_option_code`. This is a unique identifier that
        displays what carrier and what set of shipping functionalities you want
        to use.
      examples:
        - type: shipping_option_code
          properties:
            shipping_option_code: postnl:standard/insured=3000
            contract_id: 517
      properties:
        type:
          type: string
          description: |
            The way the shipping method and carrier will be selected.
          enum:
            - shipping_option_code
          example: shipping_option_code
        properties:
          $ref: '#/components/schemas/shipping-option-code-properties'
      required:
        - type
        - properties
    dimension:
      title: Dimension
      type: object
      description: Dimension in the specified unit
      properties:
        length:
          type: number
          description: length in specified unit
          minimum: 0
          example: 15
        width:
          type: number
          description: width in specified unit
          minimum: 0
          example: 20.5
        height:
          type: number
          description: height in specified unit
          minimum: 0
          example: 37
        unit:
          $ref: '#/components/schemas/dimension-units'
      required:
        - length
        - width
        - height
        - unit
    weight:
      title: Weight
      type: object
      description: Weight in the specified unit
      properties:
        value:
          type: number
          description: Weight value
          exclusiveMinimum: 0
          example: 14.5
        unit:
          $ref: '#/components/schemas/weight-units'
      required:
        - value
        - unit
    volume:
      title: Volume
      type: object
      description: Volume in the specified unit
      properties:
        value:
          type: integer
          description: Volume value
          minimum: 0
          example: 5
        unit:
          $ref: '#/components/schemas/volume-units'
      required:
        - value
        - unit
    shipping-option-code-properties:
      title: Shipping option properties Object
      description: >-
        Contains the required properties to be sent when API client informs the
        shipping method and carrier to be used
      type: object
      properties:
        shipping_option_code:
          type:
            - string
            - 'null'
          description: >-
            The shipping option that will be or is used for shipping your
            parcel. A shipping option `code` can be retrieved from the [Create a
            list of shipping
            options](/api/v3/shipping-options/create-a-list-of-shipping-options)
            endpoint.
          example: postnl:standard/insured=3000
        contract_id:
          type:
            - integer
            - 'null'
          minimum: 1
          description: >-
            Selected shipping contract. If you haven't specified a contract for
            shipping your parcel, we will automatically select the default
            contract for the carrier that matches your shipping option. You can
            retrieve your contract IDs by using the [Retrieve a list of
            contracts](/api/v3/contracts/retrieve-a-list-of-contracts)
            operation. Otherwise, the default direct contract will be
            automatically selected.
      required:
        - shipping_option_code
    dimension-units:
      type: string
      title: Dimensional units
      enum:
        - cm
        - mm
        - m
        - yd
        - ft
        - in
      example: mm
    weight-units:
      type: string
      title: Mass Units Object
      enum:
        - kg
        - g
        - lbs
        - oz
      example: g
    volume-units:
      type: string
      title: Volume units
      enum:
        - m3
        - cm3
        - l
        - ml
        - gal
      example: l
  securitySchemes:
    HTTPBasicAuth:
      type: http
      description: >-
        Basic Authentication using API key and secrets is currently the main
        authentication mechanism.
      scheme: basic
    OAuth2ClientCreds:
      type: oauth2
      description: >-
        OAuth2 is a standardized protocol for authorization that allows users to
        share their private resources stored on one site with another site
        without having to provide their credentials. OAuth2 Client Credentials
        Grant workflow. This workflow is typically used for server-to-server
        interactions that require authorization to access specific resources.
      flows:
        clientCredentials:
          tokenUrl: https://account.sendcloud.com/oauth2/token/
          scopes:
            api: Default OAuth scope required to access Sendcloud API.

````