{
  "openapi": "3.1.0",
  "info": {
    "title": "Scurri Platform API",
    "version": "2026.1",
    "description": "This API allows you to manage consignments, including creating, updating, and retrieving details about shipments including labels and customs invoices.\n\n## Authentication\nAll 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.\n\n### API Token\nWith API token-based authentication, you must include the token in the Authorization header as an API token, e.g. Authorization: token YOUR_API_TOKEN.\nFailed requests will return a 401 HTTP code with WWW-Authenticate: Basic response header.\n\n\n### Basic Auth\nWith Basic Auth, you have to send the username and password base64-encoded in the standard Basic manner, e.g. Authorization: Basic YXBpdGVzdDphcGkgcGFzc3dvcmQgdGVzdA==.\n\nHere is some sample code in Python to generate the value of the header:\n```python\n> import base64\n> username = 'apitest'\n> password = 'api-test-password'\n> print(base64.b64encode((username + ':' + password).encode()).decode())\nYXBpdGVzdDphcGktdGVzdC1wYXNzd29yZA==\n```\n"
  },
  "tags": [
    {
      "name": "Carriers",
      "description": "The Carriers API allows you to query Scurri for the carriers that are enabled in your account.\n\nThe 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. \nThe identifier will never change, so this can be called once to get the values.\n"
    },
    {
      "name": "Carrier Services",
      "description": "The Carrier Services API allows you to query Scurri for the services that are available for each carrier.\n\nThe 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.\n"
    },
    {
      "name": "Warehouses",
      "description": "The Warehouses API allows you to retrieve a list of warehouses that you have access to (within a company).\n\nThe 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.\n"
    },
    {
      "name": "Consignments",
      "description": "This group of API calls allow you to interact with your consignments in Scurri. You can list and\nsearch through them, create new ones, update existing ones, and retrieve their details. To see consignment documents, go to the **Consignment Documents** section.\n"
    },
    {
      "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.\n\nKeep in mind that a label will be created for each package of the consignment.\n## Available label formats\nThe 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.\n\nLabels can be provided in the following formats:\n- PDF: One PDF returned with multiple labels concatenated in a single document (one label per page)\n- 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.\n- PNG: A ZIP file is returned containing all files\n- PNG list: Single file PNGs (non-zipped)\n\n\nAlternative 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.\n\nThe label format can be specified in the `documenttype` query parameter, which can take the following values:\n- PDF: `application/pdf`\n- ZPL: `application/x-zebra-zpl`\n- PNG: `image/png`\n- PNG list: `image/x-png-list`\n\n## Customs Invoice Documents\n\nScurri 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.\n\n## Natively Supported ZPL Carriers\n- An Post\n- Colissimo\n- Deutsche Post\n- DPD\n- DPD Germany  \n- DPD Ireland\n- DX  \n- Fastway\n- Generic Carrier\n- Hermes\n- Interlink  \n- ITD Carrier\n- P2P Trakpak  \n- ParcelForce  \n- PostNL  \n- Royal Mail\n- Spring Global  \n- TNT  \n- Tuffnells  \n- UKMail\n- Yodel\n"
    },
    {
      "name": "Manifests",
      "description": "The manifest process marks a list of consignments as ready to be picked up by the carrier.\nA manifest always refers to a specific warehouse and carrier. Scurri abstracts away the necessary actions and documentation\n a carrier needs and presents a common interface for the manifest process.\n\nThe endpoints in this section allow you to create a manifest for given consignments, and retrieve any relevant documents\n"
    }
  ],
  "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.\n\nPagination is provided via the offset and limit GET parameters.\n\nFor 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.\n\nExample offset URL: https://sandbox.scurri.co.uk/api/v1/company/test-company/consignments/?offset=000ed1bfb93c43319ec79247f50dfd3c\n\nYou 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. \n\nThe Despatched, Delivered and Exception statuses are only available if Tracking has been enabled on your account.\n",
        "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.\nDefault: ''.\n"
          },
          {
            "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",
              "default": "application/pdf"
            },
            "description": "Document MIME type.  \n\n**Allowed values:**\n* `application/pdf`\n* `image/png`\n* `application/x-zebra-zpl`\n* `image/x-png-list`\n"
          },
          {
            "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.\n\nScurri will return the correct documentation for the specified carrier.\n\nKeep in mind that, because the document generation is kicked off asynchronously by the previous API call, the documents may \nnot be ready, when you execute this API call. In that case, you should retry after a while.\n",
        "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."
          },
          "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"
          },
          "brand": {
            "type": "string",
            "description": "The dispatching brand for appropriate tax numbers and declarations.",
            "example": "LeMark",
            "maxLength": 255
          },
          "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"
              },
              "recipient_type": {
                "type": "string",
                "description": "Classifies the destination as a Business or Consumer to determine the correct information and duties that apply to the shipment. Defaults to blank when not specified.",
                "maxLength": 8,
                "default": "",
                "enum": [
                  "",
                  "Business",
                  "Consumer"
                ]
              },
              "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"
              },
              "declaration_statements": {
                "type": "array",
                "maxItems": 2,
                "description": "List of declaration statements for customs.",
                "items": {
                  "type": "string",
                  "maxLength": 270
                },
                "example": [
                  "The sender is the exporter of the goods declared herein and is responsible for the information provided on this declaration.",
                  "The goods described in this consignment are of UK origin."
                ]
              }
            }
          },
          "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.\nWeight is always defined in kilograms.\n",
        "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, in kilograms (kg).",
            "minimum": 0,
            "example": 1
          },
          "length": {
            "type": "number",
            "description": "Numeric length of the package, in centimetres (cm).",
            "example": 5
          },
          "width": {
            "type": "number",
            "description": "Numeric width of the package, in centimetres (cm).",
            "example": 2
          },
          "height": {
            "type": "number",
            "description": "Numeric height of the package, in centimetres (cm).",
            "example": 10
          },
          "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.\n",
            "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.\nThe reference doesn't need to be unique per company or per item.\n",
            "maxLength": 255,
            "example": "SC1234"
          }
        }
      },
      "Item": {
        "type": "object",
        "description": "Defines item data for a specific package. A package may have one or more items.\nWeight is always defined in kilograms.\n",
        "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 '\n'purposes. Only required if sending to an international '\n'destination.'\n",
            "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."
          },
          "standardised_product_id": {
            "type": "string",
            "description": "Universal product barcode string (e.g., GTIN, UPC, EAN or ISBN).",
            "maxLength": 255,
            "example": "5012345678900"
          },
          "standardised_product_id_type": {
            "type": "string",
            "description": "Barcode format type for the standardised product ID. Can be null.",
            "maxLength": 255,
            "examples": [
              "GTIN",
              "UPC",
              "EAN",
              "ISBN"
            ]
          },
          "manufacturer_product_id": {
            "type": "string",
            "description": "The product's alphanumeric Manufacturer Part Number (MPN) or internal factory code.",
            "maxLength": 255
          },
          "commodity_description": {
            "type": "string",
            "description": "The description of the item to aid consolidation/clearance.",
            "maxLength": 255,
            "examples": [
              "Men's cotton apparel",
              "Wooden dining furniture",
              "Plastic children's toys"
            ]
          },
          "cpsc_regulatory_details": {
            "type": "object",
            "description": "Consumer Product Safety Commission (CPSC) regulatory details. All fields are required when provided.",
            "properties": {
              "certifier_id": {
                "type": "string",
                "description": "The certifier's CPSC Product Registry identifier.",
                "maxLength": 255,
                "example": "CR-883921"
              },
              "product_id": {
                "type": "string",
                "description": "The products CPSC Product Registry identifier.",
                "maxLength": 255,
                "example": "PRD-4728193"
              },
              "version_id": {
                "type": "string",
                "description": "The product's CPSC certificate version identifier.",
                "maxLength": 255,
                "examples": [
                  "1.0",
                  "2.1"
                ]
              }
            }
          },
          "eudr_regulatory_details": {
            "type": "object",
            "description": "EU Deforestation Regulation (EUDR) regulatory details. All fields are required when provided.",
            "properties": {
              "dds_reference_number": {
                "type": "string",
                "description": "The Due Diligence Statement (DDS) reference number required to support compliance with the EUDR legislation.",
                "maxLength": 255,
                "example": "26GB9A8B7C6D5"
              }
            }
          }
        }
      },
      "Options": {
        "description": "Carrier-specific options for a consignment. If an option does not apply\nto the carrier for the consignment, it is ignored. Note that options\nare not set if a consignment cannot be allocated to a carrier service.\n",
        "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"
          },
          {
            "type": "object",
            "properties": {
              "carrier": {
                "type": "string",
                "description": "Carrier name or code.",
                "maxLength": 64,
                "example": "Generic Carrier"
              },
              "service": {
                "type": "string",
                "description": "Carrier service selected for the consignment.",
                "maxLength": 128,
                "example": "Generic Domestic Service GDOM"
              },
              "consignment_number": {
                "type": "string",
                "description": "The consignment number.",
                "maxLength": 255,
                "example": "000000000008108293"
              },
              "current_status": {
                "type": "object",
                "description": "Current status of the consignment.",
                "properties": {
                  "short_form": {
                    "type": "string",
                    "description": "Short-form version of the current status.",
                    "maxLength": 10,
                    "example": "Printed"
                  },
                  "status": {
                    "type": "string",
                    "description": "Full description of the current status.",
                    "maxLength": 40,
                    "example": "Printed - Ready to Manifest"
                  },
                  "rejection_reason": {
                    "type": "string",
                    "description": "Reason for rejection, if the consignment has been rejected. Null if not rejected.",
                    "maxLength": 100,
                    "example": "Failed to generate a label."
                  }
                }
              },
              "tracking_url": {
                "type": "string",
                "description": "Carrier tracking URL for the consignment.",
                "maxLength": 200,
                "example": "https://www.generic-test-carrier.co.uk/tracking/?reference=0123456789"
              }
            }
          }
        ]
      },
      "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"
          }
        }
      }
    }
  }
}