--- updatedAt: 2026-04-24T07:39:03.000Z agentTools: projectIndex: https://developer.xentral.com/llms.txt --- # Create shipment The request a Xentral instance makes to an external carrier service to generate a shipping label. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Carrier Integration Service Contract", "version": "v0.1", "description": "The Carrier Integration Service Contract defines the interface for setting up custom shipping methods inside of Xentral based on external carrier services. This contract is used by partners to implement the required endpoints to integrate their carrier services with Xentral. The contract defines the following endpoints:\n\n- **GET /xentral/liveness**: Check the liveness of the service\n- **GET /xentral/carriers**: A list of available carriers and their products\n- **POST /xentral/shippingLabel**: Get a shipping label\n\nThe contract also defines the request and response bodies for each endpoint.", "contact": { "name": "Xentral", "url": "https://xentral.com", "email": "api@xentral.com" } }, "tags": [ { "name": "Carrier Integration Service Contract", "description": "All endpoints required to be implemented by partners to integrate their carrier services with Xentral." } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer token obtained in POST /tokens endpoint or pregenerated in the system." } } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "https://{domain}", "description": "The carrier integration service URL", "variables": { "domain": { "default": "xentral.example-carrier-service.com" } } } ], "x-readme": { "samples-languages": [] }, "paths": { "/xentral/shipments": { "post": { "tags": [ "Carrier Integration Service Contract" ], "operationId": "xentral.carrierIntegrationService.shipmentCreate", "summary": "Create shipment", "description": "The request a Xentral instance makes to an external carrier service to generate a shipping label.", "parameters": [ { "in": "header", "name": "Accept-Language", "schema": { "type": "string", "example": "de-DE", "pattern": "[a-z]{2}-[A-Z]{2}", "description": "ISO 15897 locale." }, "required": true, "description": "The used locale of the user making the request. Use this header to determine the language of the localised fields in the response" } ], "requestBody": { "description": "Request body for generating a shipment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "recipient", "sender", "carrier", "shipmentType" ], "properties": { "recipient": { "type": "object", "description": "When no Drop Off Location is specified, the recipient address is the location where the shipment is being send to.", "required": [ "name", "address", "city", "zip", "country" ], "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "addressLine2": { "type": "string" }, "addressLine3": { "type": "string" }, "company": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } } }, "dropOffLocation": { "type": "object", "description": "An optional of the address where the packages should be delivered. If not provided, the recipient address will be used.", "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "addressLine2": { "type": "string" }, "addressLine3": { "type": "string" }, "pickUpId": { "type": "string", "description": "The ID of the pick up point" }, "company": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } } }, "sender": { "type": "object", "required": [ "name", "address", "city", "zip", "country" ], "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "addressLine2": { "type": "string" }, "addressLine3": { "type": "string" }, "company": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } } }, "reference": { "type": "string", "description": "A reference description that can be printed on the label. Depending on the Xentral configuration can for example contain a Delivery Note number, or some other information", "example": "Xentral order: 1234566" }, "carrier": { "type": "object", "required": [ "id", "product" ], "properties": { "id": { "type": "string" }, "product": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "carrierOptions": { "type": "array", "items": { "type": "object", "description": "Identifies the carrier option and sets the value for the option", "required": [ "id", "value" ], "properties": { "id": { "type": "string", "description": "The ID of the option", "example": "age-check" } }, "oneOf": [ { "properties": { "value": { "type": "string", "description": "The value of a string option", "example": "economy" } } }, { "properties": { "value": { "type": "number", "description": "The value of a numeric option", "example": 12.3 } } }, { "properties": { "value": { "type": "boolean", "description": "The value of a boolean option", "example": true } } }, { "properties": { "value": { "type": "object", "description": "The id of a value when option type is select", "properties": { "id": { "type": "string" } }, "example": { "id": "1" } } } } ] } } } } } }, "parcels": { "type": "array", "minItems": 1, "description": "The parcels that are part of the shipment. The list contains at least one parcel.", "required": [ "items" ], "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID of the parcel. This ID should be used in a response to match parcels with labels.", "example": "675ea55c-ab95-425a-977f-c70da64aa3e2" }, "weight": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "kg" ] } } }, "dimensions": { "type": "object", "properties": { "length": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "cm" ] } } }, "width": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "cm" ] } } }, "height": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "cm" ] } } } } } } } }, "insurance": { "type": "object", "required": [ "isInsured" ], "properties": { "isInsured": { "type": "boolean" }, "value": { "description": "Money object with amount and currency", "example": { "amount": "13.37", "currency": "EUR" }, "type": "object", "additionalProperties": false, "properties": { "amount": { "description": "A string representing the amount", "type": "string", "format": "float", "example": "24.99" }, "currency": { "type": "string", "pattern": "[A-Z]{3}", "enum": [ "EUR", "USD", "JPY", "BGN", "CZK", "DKK", "GBP", "HUF", "PLN", "RON", "SEK", "CHF", "ISK", "NOK", "HRK", "RUB", "TRY", "AUD", "BRL", "CAD", "CNY", "HKD", "IDR", "ILS", "INR", "KRW", "MXN", "MYR", "NZD", "PHP", "SGD", "THB", "ZAR", "ARS", "CLP", "SAR", "AED", "QAR" ], "description": "Currency matches one of currency values as specified in ISO-4217.", "example": "PLN" } } } } }, "label": { "type": "object", "required": [ "type", "size", "orientation" ], "description": "The label options that the user has selected for the shipment", "properties": { "type": { "type": "string", "description": "The type of the label. This is used to determine the file format of the label that is requested.", "enum": [ "pdf", "png", "zpl", "gif", "jpg" ] }, "size": { "type": "string", "example": "A4", "description": "The size of the label. This is used to determine the size of the label that is printed." }, "orientation": { "type": "string", "enum": [ "portrait", "landscape" ] } } }, "deliveryNote": { "description": "Reference to another resource", "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } }, "example": { "id": "1337" } }, "return": { "description": "Reference to another resource", "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } }, "example": { "id": "1337" } }, "shipment": { "description": "Reference to another resource", "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } }, "example": { "id": "1337" } }, "salesOrder": { "description": "Reference to another resource", "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } }, "example": { "id": "1337" } }, "shipmentType": { "type": "string", "enum": [ "outbound", "return" ], "description": "Informs whether the shipment is of outbound or return type." }, "exportDeclarations": { "type": "array", "description": "Export declaration lines for customs; one entry per exported item. Contains all customs-related item data required for international shipments.", "items": { "type": "object", "description": "Export declaration line for customs. Represents one exported item with all customs-related data required for international shipments.", "required": [ "itemNumber", "title", "price", "currency", "quantity", "unitOfMeasure", "manufacturerCountry" ], "properties": { "itemNumber": { "type": "string", "description": "Article number", "example": "12345" }, "title": { "type": "string", "description": "Item title/name", "example": "Book" }, "description": { "type": "string", "description": "Item description", "example": "Harry Steward biography first edition" }, "price": { "type": "number", "format": "float", "description": "Sales price per unit", "example": 15.99 }, "currency": { "type": "string", "pattern": "[A-Z]{3}", "description": "ISO 4217 currency code", "example": "EUR" }, "quantity": { "type": "number", "format": "float", "description": "Quantity of exported items", "example": 10 }, "unitOfMeasure": { "type": "string", "description": "Unit of measure (e.g. PCS, GM, KG)", "example": "PCS" }, "customsTariffNumber": { "type": "string", "description": "Customs tariff code of the article; omitted when the article has none", "example": "84713000" }, "exportControlClassificationNumber": { "type": "string", "description": "Export control classification number (e.g. ECCN, only for US shipments)", "example": "US123456789" }, "manufacturerCountry": { "type": "string", "description": "Country of origin/manufacture", "example": "US" }, "weight": { "type": "object", "description": "Weight of one unit of the item, in kg", "required": [ "netValue", "grossValue" ], "properties": { "netValue": { "type": "number", "format": "float", "description": "Net weight (excluding packaging), in kg", "example": 0.1 }, "grossValue": { "type": "number", "format": "float", "description": "Gross weight (including packaging), in kg", "example": 0.7 } } } } } } } }, "examples": { "Simple Shipment Request": { "value": { "recipient": { "name": "John Doe", "address": "123 Main St", "addressLine2": "Apt 1", "addressLine3": "Floor 2", "company": "Xentral", "city": "Anytown", "state": "CA", "zip": "12345", "country": "US", "email": "john.doe@xentral.com", "phone": "+1234567890" }, "sender": { "name": "Jane Doe", "address": "123 Main St", "city": "Anytown", "state": "CA", "zip": "12345", "country": "US", "email": "jane.doe@xentral.com", "phone": "+1234567890" }, "carrier": { "id": "post-ch", "product": { "id": "post-ch-express" } }, "parcels": [ { "id": "01946f45-86fa-7665-af03-4f32733e5700", "weight": { "value": 1, "unit": "kg" }, "dimensions": { "length": { "value": 10, "unit": "cm" }, "width": { "value": 10, "unit": "cm" }, "height": { "value": 10, "unit": "cm" } } } ], "deliveryNote": { "id": "123456789" }, "shipment": { "id": "123456789" }, "salesOrder": { "id": "123456789" }, "shipmentType": "outbound" } }, "Shipment Request with alternative drop off location": { "value": { "recipient": { "name": "John Doe", "address": "123 Main St", "addressLine2": "Apt 1", "addressLine3": "Floor 2", "company": "Xentral", "city": "Anytown", "state": "CA", "zip": "12345", "country": "US", "email": "john.doe@xentral.com", "phone": "+1234567890" }, "sender": { "name": "Jane Doe", "address": "123 Main St", "city": "Anytown", "state": "CA", "zip": "12345", "country": "US", "email": "jane.doe@xentral.com", "phone": "+1234567890" }, "dropOffLocation": { "name": "Jane Doe", "pickUpId": "123456789" }, "carrier": { "id": "post-ch", "product": { "id": "post-ch-express" } }, "parcels": [ { "id": "01946f45-86fa-7665-af03-4f32733e5700", "weight": { "value": 1, "unit": "kg" }, "dimensions": { "length": { "value": 10, "unit": "cm" }, "width": { "value": 10, "unit": "cm" }, "height": { "value": 10, "unit": "cm" } } } ], "deliveryNote": { "id": "123456789" }, "shipment": { "id": "123456789" }, "salesOrder": { "id": "123456789" }, "shipmentType": "outbound" } } } } } }, "responses": { "200": { "description": "Response body for generating a shipment.", "content": { "application/json": { "schema": { "required": [ "shippingLabels", "id", "carrier" ], "type": "object", "properties": { "shippingLabels": { "type": "array", "items": { "type": "object", "required": [ "parcelId", "trackingId", "trackingUrl", "label" ], "properties": { "parcelId": { "type": "string", "description": "The Unique ID of the parcel that this shipping label belongs to.", "example": "675ea55c-ab95-425a-977f-c70da64aa3e2" }, "trackingId": { "type": "string", "description": "The tracking ID for the shipment", "example": "123456789" }, "trackingUrl": { "description": "The tracking URL for the shipment", "type": "string", "example": "https://tracking.post.ch/track/123456789" }, "label": { "type": "object", "required": [ "type", "data" ], "description": "A representation of a label that can be printed for a shipment. It contains information about the file format and the file itself.", "example": { "type": "pdf", "data": "iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAADOSURBVHgB1ZZpDoUwCITxnaT3v1SP0mdN49YNEDJKbPxhmfnSBVwS0frg4kfguAKEQBTjuibJZ2Tt7HGO/XMIxzvGZB5Z8+xRfA+A+wRLiJZ2BdCb6GGeowkwSrA0HwLMEi3MpwAcgSfmLACukDaHBSARlM5lA3CFpaslApgZaLZKDNAz0h5WFUALQntT1AB3CG2tKLnwdvyxLYAeQug1hBYiaCmGNiNoO35iztV45y+ZpfkMogLwMB9BVABe5j2ICsDTvAVRxrJRAAPejv8TASt8b/v+egAAAABJRU5ErkJggg==" }, "properties": { "type": { "type": "string", "example": "pdf", "enum": [ "pdf", "png", "zpl", "gif", "jpg" ] }, "data": { "type": "string", "description": "The data of the label. If the label is PDF, PNG, or GIF, the data is base64 encoded. If the label is ZPL, the data is the ZPL code.", "example": "iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAADOSURBVHgB1ZZpDoUwCITxnaT3v1SP0mdN49YNEDJKbPxhmfnSBVwS0frg4kfguAKEQBTjuibJZ2Tt7HGO/XMIxzvGZB5Z8+xRfA+A+wRLiJZ2BdCb6GGeowkwSrA0HwLMEi3MpwAcgSfmLACukDaHBSARlM5lA3CFpaslApgZaLZKDNAz0h5WFUALQntT1AB3CG2tKLnwdvyxLYAeQug1hBYiaCmGNiNoO35iztV45y+ZpfkMogLwMB9BVABe5j2ICsDTvAVRxrJRAAPejv8TASt8b/v+egAAAABJRU5ErkJggg==" } } } } } }, "id": { "type": "string", "description": "The Unique ID of the shipment. This ID is used to cancel the shipment and must be unique across all shipments generated by the service.", "example": "675ea55c-ab95-425a-977f-c70da64aa3e2" }, "carrier": { "type": "object", "description": "Information about the carrier", "example": { "name": "Post Swiss" }, "properties": { "name": { "type": "string", "description": "The name of the carrier", "example": "Post Swiss" } } }, "customsDocuments": { "type": "array", "description": "Optional list of customs documents (e.g. CN22, CN23, COO) returned by the carrier. Each document includes typeCode, optional fileName, and base64-encoded fileContent.", "items": { "type": "object", "required": [ "typeCode", "fileContent" ], "properties": { "typeCode": { "type": "string", "description": "Document type code (e.g. COO, CN22, CN23)", "example": "CN23" }, "fileName": { "type": "string", "description": "Optional file name for the document", "example": "CN23_form.pdf" }, "fileContent": { "type": "string", "description": "Base64-encoded document content (e.g. PDF)", "format": "byte" } } } } } } } } }, "400": { "description": "IETF RFC 9457 Problem API compliant response", "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type", "title", "violations" ], "properties": { "type": { "type": "string", "enum": [ "https://api.xentral.biz/problems/request-validation" ] }, "title": { "type": "string", "minLength": 1, "example": "Request payload validation failed." }, "violations": { "oneOf": [ { "type": "array", "items": { "type": "object", "example": { "username": [ "This value should not be blank." ], "email": [ "This value is not a valid email address." ] } }, "description": "This field will be a mirrored request payload with only invalid fields and values replaced by error messages." }, { "type": "object", "example": { "_": [ "This value should contain at most `9` elements." ] }, "description": "This field will be a mirrored request payload with only invalid fields and values replaced by error messages." } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "title", "messages" ], "properties": { "type": { "type": "string", "enum": [ "https://api.xentral.biz/problems/generic-validation" ] }, "title": { "type": "string", "minLength": 1 }, "messages": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "title", "messages" ], "properties": { "type": { "type": "string", "enum": [ "https://api.xentral.biz/problems/conflict" ] }, "title": { "type": "string", "minLength": 1 }, "messages": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "title", "items" ], "properties": { "type": { "type": "string", "enum": [ "https://api.xentral.biz/problems/conflictItems" ] }, "title": { "type": "string", "minLength": 1 }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "messages" ], "properties": { "id": { "type": "integer" }, "title": { "type": "string", "minLength": 1 }, "messages": { "type": "array", "items": { "type": "string" } } } } } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "title", "scopes" ], "properties": { "type": { "type": "string", "enum": [ "https://developer.xentral.com/reference/problems#token-scopes" ] }, "title": { "type": "string", "minLength": 1 }, "scopes": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "title", "messages" ], "properties": { "type": { "type": "string", "enum": [ "https://api.xentral.biz/problems/generic-validation" ] }, "title": { "type": "string", "minLength": 1 }, "messages": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } ] } } } }, "401": { "description": "Unable to authenticate the client", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message explaining why the request failed.", "example": "Missing required scopes: customer:create." } } }, "example": { "message": "Missing required scopes: customer:create." } }, "text/html": { "schema": { "type": "string", "example": "Unauthorized" } } } }, "403": { "description": "Unable to authorize the client" }, "404": { "description": "Resource was not found or not enough access privileges" } } } } } } ```