openapi: 3.1.0
info:
  title: Scurri Platform API
  version: 1.0.0
  description: >
    This API allows you to manage consignments, including creating, updating,
    and retrieving details about shipments including labels and customs
    invoices.


    ## Authentication

    All requests must be authenticated using either Basic Auth or API
    token-based authentication. If you have been provided with an API token, you
    should use token-based authentication.


    ### API Token

    With API token-based authentication, you must include the token in the
    Authorization header as an API token, e.g. Authorization: token
    YOUR_API_TOKEN.

    Failed requests will return a 401 HTTP code with WWW-Authenticate: Basic
    response header.



    ### Basic Auth

    With Basic Auth, you have to send the username and password base64-encoded
    in the standard Basic manner, e.g. Authorization: Basic
    YXBpdGVzdDphcGkgcGFzc3dvcmQgdGVzdA==.


    Here is some sample code in Python to generate the value of the header:

    ```python`

    > import base64

    > username = 'apitest'

    > password = 'api-test-password'

    > print(base64.b64encode((username + ':' + password).encode()).decode())

    YXBpdGVzdDphcGktdGVzdC1wYXNzd29yZA==

    ```
tags:
  - name: Carriers
    description: >
      The Carriers API allows you to query Scurri for the carriers that are
      enabled in your account.


      The result contains the identifier for each carrier, which you can use in
      the rest of the API calls, whenever a Carrier needs to be specified. 

      The identifier will never change, so this can be called once to get the
      values.
  - name: Carrier Services
    description: >
      The Carrier Services API allows you to query Scurri for the services that
      are available for each carrier.


      The result contains the identifier for each service, which you can use in
      the rest of the API calls, whenever a Carrier Service needs to be
      specified.
  - name: Warehouses
    description: >
      The Warehouses API allows you to retrieve a list of warehouses that you
      have access to (within a company).


      The result contains the identifier for each warehouse, which you can use
      in the rest of the API calls, whenever a **Warehouse** needs to be
      specified.
  - name: Consignments
    description: >
      This group of API calls allow you to interact with your consignments in
      Scurri. You can list and

      search through them, create new ones, update existing ones, and retrieve
      their details. To see consignment documents, go to the **Consignment
      Documents** section.
  - name: Consignment Documents
    description: >
      You can use this API call to get the label and any customs invoice
      documents required for a specific consignment, if required.


      Keep in mind that a label will be created for each package of the
      consignment.

      ## Available label formats

      The resulting documents are returned as strings within the JSON response.
      These are plaintext in the case of ZPL labels, all other formats are
      base64-encoded binary files. 

      Labels can be provided in the following formats:

      - PDF: One PDF returned with multiple labels concatenated in a single
      document (one label per page)

      - ZPL: Can be configured as 230 or 300 DPI resolution. It's also possible
      to specify the required label resolution or compress the label in the
      request.

      - PNG: A ZIP file is returned containing all files

      - PNG list: Single file PNGs (non-zipped)



      Alternative label formats are also available, for example 8"x4". To enable
      this feature on your account, contact Scurri support. Once enabled the
      label customisation parameter can be used.


      The label format can be specified in the `documenttype` query parameter,
      which can take the following values:

      - PDF: `application/pdf`

      - ZPL: `application/x-zebra-zpl`

      - PNG: `image/png`

      - PNG list: `image/x-png-list`


      ## Customs Invoice Documents


      Scurri will return the documents the carrier requires, only if the carrier
      does require them for the specific consignment.Another thing to note about
      customs invoice documents is that they can be either in a **6"x4"** size
      (for thermal printer) or in an **A4** size (for a document printer). Your
      account can be configured, so that **6"x4"** thermal invoices can be
      concatenated with the respective label. This makes it easier to send each
      file to the correct printer. Note that setting documenttype to
      `application/x-zebra-zpl` only impacts labels, not invoices - they remain
      PDF as they are A4.


      ## Natively Supported ZPL Carriers

      - An Post

      - Colissimo

      - Deutsche Post

      - DPD

      - DPD Germany  

      - DPD Ireland

      - DX  

      - Fastway

      - Generic Carrier

      - Hermes

      - Interlink  

      - ITD Carrier

      - P2P Trakpak  

      - ParcelForce  

      - PostNL  

      - Royal Mail

      - Spring Global  

      - TNT  

      - Tuffnells  

      - UKMail

      - Yodel
  - name: Manifests
    description: >
      The manifest process marks a list of consignments as ready to be picked up
      by the carrier.

      A manifest always refers to a specific warehouse and carrier. Scurri
      abstracts away the necessary actions and documentation
       a carrier needs and presents a common interface for the manifest process.

      The endpoints in this section allow you to create a manifest for given
      consignments, and retrieve any relevant documents
servers:
  - url: https://sandbox.scurri.co.uk
    description: Scurri Sandbox Environment
paths:
  /_api/v1/company/{company_slug}/carriers:
    parameters:
      - schema:
          type: string
        name: company_slug
        in: path
        required: true
        description: the slug of your company
    get:
      summary: List Available Carriers
      tags:
        - Carriers
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierListResponse'
        '401':
          description: >-
            Authentication failed or user does not have access to the requested
            resource.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Unauthorized error message.
      security:
        - TokenAuth: []
      operationId: list_available_carriers
      description: List all the carriers for the logged in user
  /_api/v1/company/{company_slug}/carrierservices:
    parameters:
      - schema:
          type: string
        name: company_slug
        in: path
        required: true
      - schema:
          type: boolean
        name: enhancements
        in: query
        required: false
        description: Whether to include enhanced services in the response.
      - schema:
          type: boolean
        name: package_types
        in: query
        required: false
        description: Whether to include package types in the response.
    get:
      summary: List Available Carrier Services
      tags:
        - Carrier Services
      responses:
        '200':
          description: Request was successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceListResponse'
        '401':
          description: >-
            Authentication failed or user does not have access to the requested
            resource.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Unauthorized error message."
      operationId: list_available_carrier_services
      description: List all the carrier services for the logged in user
      security:
        - TokenAuth: []
  /_api/v1/company/{company_slug}/warehouses:
    parameters:
      - schema:
          type: string
        name: company_slug
        in: path
        required: true
    get:
      summary: List Available Warehouses
      tags:
        - Warehouses
      responses:
        '200':
          description: Request was successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WarehouseListResponse'
        '401':
          description: >-
            Authentication failed or user does not have access to the requested
            resource.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Unauthorized error message."
      operationId: list_available_warehouses
      security:
        - TokenAuth: []
  /_api/v1/company/{company_slug}/consignments:
    get:
      operationId: listConsignments
      description: >
        You can use this API call to retrieve the list of consignments in
        Scurri.


        Pagination is provided via the offset and limit GET parameters.


        For the `offset`, we don't use an integer value but instead use the last
        `identifier` of the current batch. The next value returned with the
        response body contains a URL you can use to retrieve the next batch.


        Example offset URL:
        https://sandbox.scurri.co.uk/api/v1/company/test-company/consignments/?offset=000ed1bfb93c43319ec79247f50dfd3c


        You can also use this API call to search for consignments using specific
        criteria, either for a specific `identifier` or for consignments of a
        specific status. Searching by `identifier` only returns a single
        consignment. 


        The Despatched, Delivered and Exception statuses are only available if
        Tracking has been enabled on your account.
      tags:
        - Consignments
      summary: List all consignments
      parameters:
        - schema:
            type: string
          name: company_slug
          in: path
          required: true
        - schema:
            type: string
          name: offset
          in: query
          required: false
          description: >
            The offset for any pagination. This is the string identifier of the
            last consignment entry in the current batch.

            Default: ''.
        - schema:
            type: integer
          name: limit
          in: query
          required: false
          description: 'How many results to return for a request. Default: 10.'
        - schema:
            type: string
          name: status
          in: query
          required: false
          example: Unallocated
          description: Search for consignments with a specific status.
        - schema:
            type: string
          name: identifier
          in: query
          required: false
          example: myidentifier
          description: Search for the consignment with the given identifier.
      responses:
        '200':
          description: Successfully retrieved list of consignments
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: >-
                      Total number of consignments matching the search criteria.
                      Count will decrease with each subsequent page.
                  next:
                    type: string
                    description: >-
                      URL to the next page of results, if available. Returned as
                      `None` if no further pages are available.
                    example: >-
                      https://sandbox.scurri.co.uk/api/v1/company/test-company/consignments/?offset=000ed1bfb93c43319ec79247f50dfd3c
                  results:
                    type: array
                    description: A list of consignments matching the search criteria.
                    items:
                      $ref: '#/components/schemas/ConsignmentResponse'
        '401':
          description: >-
            Authentication failed or user does not have access to the requested
            resource.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Unauthorized error message."
      security:
        - TokenAuth: []
    post:
      operationId: importConsignment
      parameters:
        - schema:
            type: string
          name: company_slug
          in: path
          required: true
      tags:
        - Consignments
      summary: Import a new consignment
      description: >-
        Creates a new consignment (shipment) for the company. The consignment
        can be allocated or unallocated, domestic or international.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsignmentImportRequest'
      responses:
        '200':
          description: >-
            The batch request was successfully received and processed by the
            application. Check the `success` array for successfully imported
            consignment identifiers and the `errors` object, which maps the
            failed item's original request index to a specific error message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: array
                    description: List of identifiers for created consignments.
                    items:
                      type: string
                    example:
                      - 8a12630db404424b943e131ce4ee3976
                  errors:
                    description: >-
                      A map of validation errors keyed by the **zero-indexed
                      position** of the failed request item. Each value is an
                      array of failure messages.
                    example:
                      '0':
                        - >-
                          recipient: name: Ensure this value has at most 255
                          characters (it has 256).
                      '1':
                        - 'service_type: This field is required.'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: array
                    description: List of external identifiers for created consignments.
                    items:
                      type: string
                    example: []
                  errors:
                    type: object
                    description: >-
                      Object of error messages for consignments that failed to
                      be created.
                    example:
                      detail: List of consignments is expected.
      security:
        - TokenAuth: []
  /_api/v1/company/{company_slug}/consignment/{shipmentIdentifier}:
    get:
      operationId: GetConsignmentDetails
      tags:
        - Consignments
      summary: Get consignment details
      description: Retrieves details of a specific consignment (shipment).
      parameters:
        - schema:
            type: string
          name: company_slug
          in: path
          required: true
        - $ref: '#/components/parameters/shipmentIdentifier'
      responses:
        '200':
          description: Consignment details successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsignmentResponse'
        '401':
          description: Permission denied (user does not have access to this shipment)
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Permission denied error message.
        '404':
          description: Consignment not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Not found error message.
      security:
        - TokenAuth: []
    put:
      operationId: UpdateConsignment
      tags:
        - Consignments
      summary: Update a consignment
      description: >-
        Updates a consignment. Can be used to allocate or unallocate the
        consignment.
      parameters:
        - in: path
          name: company_slug
          schema:
            type: string
        - $ref: '#/components/parameters/shipmentIdentifier'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsignmentUpdateRequest'
      responses:
        '200':
          description: >-
            Consignment updated successfully. Returns the updated consignment
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsignmentResponse'
        '400':
          description: >-
            Invalid request or validation error (e.g. consignment already
            manifested/printed, invalid payload)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
                example:
                  detail: 'carrier_id: Carrier not found'
        '401':
          description: Unauthorized (user does not have access to this shipment)
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Unauthorized error message.
        '404':
          description: Consignment not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Standard Not found error message.
      security:
        - TokenAuth: []
    delete:
      summary: Cancel a consignment
      operationId: CancelConsignment
      parameters:
        - schema:
            type: string
          name: company_slug
          in: path
          required: true
        - $ref: '#/components/parameters/shipmentIdentifier'
      tags:
        - Consignments
      description: Cancels a consignment, taking any necessary actions on the carrier side
      responses:
        '204':
          description: Consignment cancelled successfully.
        '400':
          description: Cancellation request could not be carried out
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: >-
                      Error message describing what caused the cancellation to
                      fail.
                    example: >-
                      Cannot cancel shipment with status of "Cancelled at
                      2025-05-02 09:00:00"
      security:
        - TokenAuth: []
  /_api/v1/company/{company_slug}/consignment/{shipmentIdentifier}/documents:
    get:
      operationId: GetConsignmentDocuments
      tags:
        - Consignment Documents
      summary: Get consignment documents
      description: >-
        Retrieves documents (e.g., labels) for a consignment. Supports filtering
        by document type and invoice quantity.
      parameters:
        - $ref: '#/components/parameters/shipmentIdentifier'
        - in: path
          name: company_slug
          schema:
            type: string
        - in: query
          name: documenttype
          schema:
            type: string
            enum:
              - application/pdf
              - image/png
              - application/x-zebra-zpl
              - image/x-png-list
            default: application/pdf
          description: Document MIME type (e.g., application/x-zebra-zpl)
        - in: query
          name: invoice_quantity
          schema:
            type: integer
          description: Number of invoices to include
      responses:
        '200':
          description: Successfully retrieved consignment label and invoice documents.
          content:
            application/json:
              schema:
                type: object
                properties:
                  labels:
                    type: string
                    format: byte
                    description: >-
                      Plaintext or base64-encoded string containing label data
                      for the consignment. Format depends on the requested
                      document type (PDF, PNG, ZPL, etc.).
                  invoices:
                    type: string
                    format: byte
                    description: >-
                      Base64-encoded invoice data for the consignment, if
                      required by the carrier/destination. May be null if not
                      applicable.
        '400':
          description: >-
            Invalid request or validation error (e.g. consignment not ready for
            printing, invalid parameters)
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Error message describing the validation or request error.
                    example: Consignment not ready for printing.
        '401':
          description: Permission denied (user does not have access to this shipment)
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Permission denied error message.
        '404':
          description: Consignment not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Standard Not found error message.
        '408':
          description: Label generation timed out
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Standard Timeout error message.
        '409':
          description: Concurrency error (conflict)
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Conflict error message.
      security:
        - TokenAuth: []
  /_api/v1/company/{company_slug}/manifest:
    post:
      operationId: CreateManifest
      tags:
        - Manifests
      summary: Create a new manifest
      description: >-
        Initiates the manifest process for a given carrier and warehouse,
        specifying the consignments to include in the manifest.
      parameters:
        - schema:
            type: string
          name: company_slug
          in: path
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManifestRequest'
      responses:
        '202':
          description: Manifest created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  identifier:
                    type: string
                    description: Unique identifier for the created manifest.
                    example: '2432'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  details:
                    type: string
                    description: >-
                      The error that occurred in the format `<field>: <error
                      message>`.
                    example: 'carrier_id: Carrier not found'
      security:
        - TokenAuth: []
  /_api/v1/company/{company_slug}/manifest/{manifest_id}/documents:
    get:
      summary: Get documents for a specific manifest
      description: >
        You can use this API call to get the manifest documentation (as an
        A4-size PDF file) that you need to hand-in to the carrier.


        Scurri will return the correct documentation for the specified carrier.


        Keep in mind that, because the document generation is kicked off
        asynchronously by the previous API call, the documents may 

        not be ready, when you execute this API call. In that case, you should
        retry after a while.
      operationId: GetManifestDocuments
      tags:
        - Manifests
      parameters:
        - schema:
            type: string
          name: company_slug
          in: path
          required: true
        - name: manifest_id
          in: path
          required: true
          description: Unique identifier for the manifest.
          schema:
            type: string
      responses:
        '200':
          description: Documents retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  documents:
                    type: array
                    items:
                      type: string
                      description: >-
                        PDF document for the manifest encoded as a base64
                        string.
        '204':
          description: The manifest documents are not yet available.
        '400':
          description: Indicates that there was something wrong with the manifest request
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: >-
                      The error that occurred in the format `<field>: <error
                      message>`.
        '409':
          description: Manifesting has failed.
      security:
        - TokenAuth: []
components:
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Token-based authentication. Use 'token <your_token>' as the value.
  parameters:
    shipmentIdentifier:
      name: shipmentIdentifier
      in: path
      schema:
        type: string
      description: Unique identifier for the consignment (shipment).
  schemas:
    Warehouse:
      type: object
      properties:
        identifier:
          type: string
          description: A unique, human readable, identifier for the service.
          example: api-test-company|Test Warehouse
        name:
          type: string
          description: The name of the warehouse.
          example: Test Warehouse
      required:
        - identifier
        - name
    Service:
      type: object
      title: ServiceResponse
      properties:
        carrier_id:
          type: string
          description: the name of the carrier to which the service belongs
          example: Generic Carrier
        identifier:
          type: string
          description: A unique, human readable, identifier for the service.
          example: Generic Carrier|Generic Domestic Service GDOM
        name:
          description: The name of the service
          type: string
          example: Next Day
        enhancements:
          description: >-
            List of enhancements supported by the service. Becomes available
            when the `enhancements` query parameter is passed as `true`.
          type: array
          items:
            type: string
          example:
            - dangerous_goods
        package_types:
          description: >-
            List of package types supported by the service. Becomes available
            when the `package_types` query parameter is passed as `true`.
          type: array
          items:
            type: string
          example:
            - parcel
      required:
        - carrier_id
        - identifier
        - name
    ConsignmentBase:
      type: object
      description: Common fields for consignment creation and update.
      properties:
        identifier:
          type: string
          description: Unique identifier for the consignment (shipment).
          minLength: 1
          maxLength: 255
          example: 8a12630db404424b943e131ce4ee3976
        order_number:
          type: string
          description: Order number associated with the consignment.
          minLength: 1
          maxLength: 255
          example: ORD123456
        create_date:
          type: string
          format: date-time
          description: Date and time when the consignment was created.
        expected_delivery_date:
          type: string
          format: date
          description: Expected delivery date for the consignment.
        carrier:
          type: string
          description: Carrier name or code.
          maxLength: 64
          example: Generic Carrier
        service_id:
          type: string
          description: Service identifier (e.g., carrier and service name).
          maxLength: 128
          example: Generic Carrier|Generic Domestic Service GDOM
        warehouse_id:
          type: string
          description: Warehouse identifier.
          maxLength: 64
          example: api-company-slug|Warehouse Name
        shipping_method:
          type: string
          description: Shipping method.
          maxLength: 255
        shipping_date:
          type: string
          description: Shipping date.
          example: '2019-08-24'
        order_value:
          type: number
          description: Value of the order.
          minimum: 0
          example: 100
        currency:
          type: string
          description: Currency code
          minLength: 3
          maxLength: 3
          example: EUR
        delivery_instructions:
          type: string
          description: Delivery instructions for the carrier.
          maxLength: 255
          example: Leave with neighbour if not home
        custom_field_1:
          type: string
          description: Custom field 1 for additional data.
          maxLength: 100
        custom_field_2:
          type: string
          description: Custom field 2 for additional data.
          maxLength: 100
        custom_field_3:
          type: string
          description: >-
            Custom field 3 for additional data. This field is available upon
            request. The standard number of custom fields is 2.
          maxLength: 100
        custom_field_4:
          type: string
          description: >-
            Custom field 4 for additional data. This field is available upon
            request. The standard number of custom fields is 2.
          maxLength: 100
        custom_field_5:
          type: string
          description: >-
            Custom field 5 for additional data. This field is available upon
            request. The standard number of custom fields is 2.
          maxLength: 100
        origin_order_reference:
          type: string
          description: Reference to the original order in your system.
          maxLength: 255
          example: REF123456
        recipient:
          type: object
          required:
            - name
            - address
          description: >-
            Recipient details. At least one of 'name', 'last_name', or
            'company_name' must be provided.
          properties:
            name:
              type: string
              description: Full name of the recipient.
              minLength: 1
              maxLength: 255
              example: John Doe
            first_name:
              type: string
              description: First name of the recipient.
              maxLength: 255
              example: ''
            last_name:
              type: string
              description: Last name of the recipient.
              maxLength: 255
              example: John Doe
            company_name:
              type: string
              description: Company name of the recipient.
              maxLength: 255
              example: Scurri
            email_address:
              type: string
              description: Email address of the recipient.
              format: email
              maxLength: 300
              example: john.doe@scurri.com
            contact_number:
              type: string
              description: Contact number of the recipient.
              maxLength: 40
              example: +353 1 234 5678
            tax_identifier:
              type: string
              description: Tax identifier for the recipient.
              maxLength: 50
              example: IE1234567
            eori_number:
              type: string
              description: EORI number for customs.
              maxLength: 17
              example: GB123456789123
            address:
              type: object
              required:
                - address1
                - city
                - postcode
                - country
              description: Recipient address details.
              properties:
                address1:
                  type: string
                  description: Address line 1.
                  maxLength: 255
                  example: Innovation House
                address2:
                  type: string
                  description: Address line 2.
                  maxLength: 100
                  example: The Bullring
                address3:
                  type: string
                  description: Address line 3.
                  maxLength: 100
                  example: ''
                city:
                  type: string
                  description: City.
                  maxLength: 100
                  example: Wexford
                state:
                  type: string
                  description: State or region.
                  maxLength: 40
                  example: County Wexford
                postcode:
                  type: string
                  description: Postal code.
                  maxLength: 64
                  example: Y35 DW6E
                country:
                  type: string
                  description: Country code (ISO 2-letter).
                  minLength: 2
                  maxLength: 2
                  example: IE
                store_code:
                  type: string
                  description: Store code if applicable.
                  maxLength: 50
                  example: ''
        packages:
          type: array
          description: List of packages within the consignment.
          items:
            $ref: '#/components/schemas/Package'
        export_customs:
          type: object
          description: >-
            Export customs information. Only include field if the value is
            populated, do not include if the value is null/empty.
          properties:
            reason_for_export:
              type: string
              description: >-
                The reason for export or purpose of shipment for customs
                clearance.
              maxLength: 64
              default: merchandise
              enum:
                - merchandise
                - sample
                - documents
                - gift
                - other
                - returns
                - personal
              example: merchandise
            shipping_cost:
              type: string
              description: Shipping cost for customs declaration.
              maxLength: 16
              example: '10.00'
            ioss_number:
              type: string
              description: IOSS number for international shipments.
              maxLength: 12
              example: IM0123456789
        options:
          $ref: '#/components/schemas/Options'
        invoice:
          $ref: '#/components/schemas/Invoice'
        custom_attributes:
          $ref: '#/components/schemas/CustomAttributes'
    Package:
      type: object
      description: >
        Defines package data for a specific consignment. Dimensions are all in
        centimetres.

        Weight is always defined in kilograms.
      properties:
        description:
          type: string
          description: General description of the contents of the package.
          minLength: 1
          maxLength: 255
          example: Clothing items
        weight:
          type: number
          description: Numeric weight of the package
          minimum: 0
          example: 1
        weight_unit:
          type: string
          description: Unit of weight
          enum:
            - g
            - kg
          example: kg
        length:
          type: number
          description: Numeric length of the package
          example: 5
        width:
          type: number
          description: Numeric width of the package
          example: 2
        height:
          type: number
          description: Numeric height of the package
          example: 10
        dimensions_unit:
          type: string
          description: Unit of dimensions
          enum:
            - mm
            - cm
            - m
            - in
            - ft
          example: cm
        tracking_number:
          type: string
          readOnly: true
          description: >
            Unique identifier assigned by the carrier for tracking the package,
            if per-package tracking is supported. Read-only.
          maxLength: 255
          example: 1Z12345E0205271688
        items:
          type: array
          description: List of items in the package.
          items:
            $ref: '#/components/schemas/Item'
        reference:
          type: string
          description: >
            The package reference. This field is for associating your internal
            packages with Scurri packages.

            The reference doesn't need to be unique per company or per item.
          maxLength: 255
          example: SC1234
    Item:
      type: object
      description: >
        Defines item data for a specific package. A package may have one or more
        items.

        Weight is always defined in kilograms.
      required:
        - name
        - quantity
      properties:
        name:
          type: string
          description: The item name.
          maxLength: 255
          example: T-Shirt
        sku:
          type: string
          description: SKU (Stock Keeping Unit) of the item.
          maxLength: 255
          example: SKU12345
        quantity:
          type: integer
          description: Quantity of the item in the package.
          default: 1
          example: 2
        value:
          type: number
          description: unit value of the item
          default: 0
          maximum: 10000
          example: 10.99
        harmonisation_code:
          type: string
          description: |
            'Standard harmonisation code of the item for tariff '
            'purposes. Only required if sending to an international '
            'destination.'
          maxLength: 35
          example: '0902.10'
        country_of_origin:
          type: string
          description: Country of origin for the item (ISO 2-letter code).
          example: GB
        weight:
          type: number
          description: Weight of the item
          default: 0
          example: 500
        vat_rate:
          type: string
          maxLength: 16
          description: VAT rate applicable to the item.
        fabric_content:
          type: string
          maxLength: 255
          description: Fabric content of the item
          example: 100% Cotton
        import_type:
          type: string
          maxLength: 16
          description: Import type for the item
          example: B2B
        mid_code:
          type: string
          maxLength: 15
          description: MID (Manufacturer Identification) code for the item.
          example: GBSCU18WEX
        reference:
          type: string
          description: A field for your own internal reference
          maxLength: 255
          example: A72B
        taric_condition:
          type: string
          maxLength: 255
          description: TARIC (EU Tariff) code for the item.
    Options:
      description: |
        Carrier-specific options for a consignment. If an option does not apply
        to the carrier for the consignment, it is ignored. Note that options
        are not set if a consignment cannot be allocated to a carrier service.
      type: object
      additionalProperties:
        type: string
      example:
        signature_required: 'true'
        age_check: 'false'
    Invoice:
      type: object
      properties:
        incoterm:
          type: string
          description: Incoterm for the invoice.
          maxLength: 50
          example: DAP
    CustomAttributes:
      type: object
      description: Additional fields to customise the consignment.
      properties:
        override_sender_name:
          type: string
          description: >-
            Replaces your company's name on labels and customs documentation for
            this consignment.
          maxLength: 50
          example: Subsidiary Ltd
        override_sender_eori:
          type: string
          description: >-
            Replaces your company's EORI number on customs documentation for
            this consignment.
          maxLength: 17
          example: GB123456789000
        global_e_order_id:
          type: string
          description: Global-e order ID for consignments fulfilled through Global-e.
          maxLength: 255
          example: '1234567890'
        override_sender_address1:
          type: string
          description: >-
            Replaces address line 1 of your company's address on labels and
            customs documentation for this consignment.
          maxLength: 255
          example: 123 Business Rd
        override_send_address2:
          type: string
          description: >-
            Replaces address line 2 of your company's address on labels and
            customs documentation for this consignment.
          maxLength: 255
          example: Business Park
        override_sender_address3:
          type: string
          description: >-
            Replaces address line 3 of your company's address on labels and
            customs documentation for this consignment.
          maxLength: 255
          example: West Wing
        override_sender_city:
          type: string
          description: >-
            Replaces the city of your company's address on labels and customs
            documentation for this consignment.
          maxLength: 255
          example: London
        override_sender_state:
          type: string
          description: >-
            Replaces the state/region of your company's address on labels and
            customs documentation for this consignment.
          maxLength: 40
          example: London
        override_sender_postcode:
          type: string
          description: >-
            Replaces the postcode of your company's address on labels and
            customs documentation for this consignment.
          maxLength: 255
          example: D02 ABC
        override_sender_country:
          type: string
          description: >-
            Replaces the country of your company's address on labels and customs
            documentation for this consignment.
          example: GB
        override_sender_email:
          type: string
          description: >-
            Replaces the email address of your company on labels and customs
            documentation for this consignment.
          maxLength: 255
          example: info@subsidiary.com
        override_sender_phone:
          type: string
          description: >-
            Replaces the phone number of your company on labels and customs
            documentation for this consignment.
          maxLength: 50
          example: '+4412345678'
    ConsignmentImportRequest:
      type: array
      items:
        allOf:
          - $ref: '#/components/schemas/ConsignmentBase'
        required:
          - order_number
          - create_date
          - recipient
      description: Request body for importing a new consignment.
    ConsignmentUpdateRequest:
      allOf:
        - $ref: '#/components/schemas/ConsignmentBase'
      required:
        - order_number
        - create_date
        - recipient
      description: >-
        Request body for updating a consignment. Fields are based on
        update_domestic_allocated.json and update_domestic_unallocated.json.
    ConsignmentResponse:
      allOf:
        - $ref: '#/components/schemas/ConsignmentBase'
    CarrierListResponse:
      type: array
      items:
        type: object
        properties:
          identifier:
            type: string
            description: Unique identifier for the carrier.
            example: Generic Carrier
          name:
            type: string
            description: Name of the carrier.
            example: Generic Carrier
    WarehouseListResponse:
      type: array
      description: A list of warehouses.
      items:
        $ref: '#/components/schemas/Warehouse'
    ServiceListResponse:
      type: array
      description: A list of services.
      items:
        $ref: '#/components/schemas/Service'
    ManifestRequest:
      type: object
      description: Request body for creating a manifest.
      properties:
        warehouse_id:
          type: string
          description: Unique identifier for the warehouse.
          example: api-test-company|Test Warehouse
        carrier_id:
          type: string
          description: Unique identifier for the carrier.
          example: Generic Carrier
        consignments:
          type: array
          items:
            type: string
          description: List of consignment identifiers to include in the manifest.
          example:
            - 8a12630db404424b943e131ce4ee3976
            - 8a12630db404424b943e131ce4ee3978
    ValidationErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: 'The error that occurred in the format `<field>: <error message>`.'
          example: 'carrier_id: Carrier not found'
