{ "swagger": "2.0", "info": { "title": "ChannelShipper & Royal Mail Public API", "description": "Import your orders, retrieve your orders and generate labels.", "version": "1.0.0" }, "host": "", "basePath": "/api/v1", "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/version": { "get": { "tags": [ "Version" ], "summary": "Get API version details.", "operationId": "GetVersionAsync", "responses": { "200": { "description": "Returns details about the API version", "schema": { "$ref": "#/definitions/GetVersionResource" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } } } }, "/orders/{orderIdentifiers}": { "get": { "tags": [ "Orders" ], "summary": "Retrieve specific orders", "operationId": "GetSpecificOrdersAsync", "parameters": [ { "$ref": "#/parameters/orderIdentifiers" } ], "responses": { "200": { "description": "Return list of specific orders", "schema": { "type": "array", "items": { "$ref": "#/definitions/GetOrderInfoResource" } } }, "400": { "description": "Bad Request (Request has missing or invalid parameters and cannot be parsed)", "schema": { "type": "array", "items": { "$ref": "#/definitions/OrderErrorResponse" } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Orders" ], "summary": "Delete orders", "description": "Reserved for ChannelShipper customers only - please visit \nChannelShipper.com for more information\n\nPlease be aware labels generated on orders which are deleted are no longer valid and must be destroyed.\n\nCancelled label information is automatically shared with Royal Mail Revenue Protection, and should \na cancelled label be identified on an item in the Royal Mail Network, you will be charged on your account \nand an additional handling fee applied.\n", "operationId": "DeleteOrdersAsync", "parameters": [ { "$ref": "#/parameters/orderIdentifiers" } ], "responses": { "200": { "description": "Provides a list of deleted orders references and ids and errors for orders that failed to delete", "schema": { "$ref": "#/definitions/DeleteOrdersResource" } }, "400": { "description": "Bad Request (Request has missing or invalid parameters and cannot be parsed)", "schema": { "type": "array", "items": { "$ref": "#/definitions/OrderErrorInfo" } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden (Feature not available)" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] } }, "/orders/status": { "put": { "tags": [ "Orders" ], "summary": "Set order status", "operationId": "UpdateOrdersStatusAsync", "parameters": [ { "name": "request", "in": "body", "required": true, "description": "At least one of 'orderIdentifier' and 'orderReference' is required. Providing both is disallowed to avoid ambiguity.\n\nWhen the status is set to 'despatchedByOtherCourier', if the optional parameter 'trackingNumber' is provided \nthen the parameters 'despatchDate', 'shippingCarrier' and 'shippingService' are also required.\nThe maximum collection lenght is 100.\n", "schema": { "$ref": "#/definitions/UpdateOrdersStatusRequest" } } ], "responses": { "200": { "description": "Provides a list of orders", "schema": { "$ref": "#/definitions/UpdateOrderStatusResponse" } }, "400": { "description": "Bad Request (Request has missing or invalid parameters and cannot be parsed)", "schema": { "type": "array", "items": { "$ref": "#/definitions/OrderUpdateError" } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] } }, "/orders/{orderIdentifiers}/full": { "get": { "tags": [ "Orders" ], "summary": "Retrieve details of the specific orders", "description": "Reserved for ChannelShipper customers only - please visit ChannelShipper.com for more information", "operationId": "GetSpecificOrdersWithDetailsAsync", "parameters": [ { "$ref": "#/parameters/orderIdentifiers" } ], "responses": { "200": { "description": "Return detailed information about the orders", "schema": { "type": "array", "items": { "$ref": "#/definitions/GetOrderDetailsResource" } } }, "400": { "description": "Bad Request (Request has missing or invalid parameters and cannot be parsed)", "schema": { "type": "array", "items": { "$ref": "#/definitions/OrderErrorResponse" } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden (Feature not available)" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] } }, "/carriers": { "get": { "tags": [ "Carriers" ], "summary": "Retrieve list of carriers for the account", "operationId": "GetCarriersAsync", "responses": { "200": { "description": "Return list of carriers", "schema": { "type": "array", "items": { "$ref": "#/definitions/GetCarrierResource" } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] } }, "/services": { "get": { "tags": [ "Services" ], "summary": "Retrieve list of available services for the account, optionally filtered by carrier, destination and package", "operationId": "GetServicesAsync", "parameters": [ { "name": "destinationCountryCode", "in": "query", "type": "string", "required": false, "description": "ISO 3166-1 alpha-3 country code of the shipment destination (e.g. GBR). Must be a recognised ISO 3166-1 alpha-3 code — an unrecognised value returns a 400. Supply it to scope results to a single destination (e.g. before checkout); GBR additionally requires destinationPostcode to be set. Omit it (along with destinationPostcode, packagingFormat and packageWeight) to browse the full, unfiltered service catalogue for discovery. destinationPostcode, packagingFormat and packageWeight require destinationCountryCode to also be supplied — providing any of them without it returns a 400, since the underlying carrier lookup can only be filtered once a destination is known." }, { "name": "destinationPostcode", "in": "query", "type": "string", "required": false, "description": "Postcode of the shipment destination. Required when destinationCountryCode is GBR — a 400 is returned if it's missing or blank. For any other destination country, postcode-based filtering isn't supported, so this value is ignored even if supplied." }, { "name": "packagingFormat", "in": "query", "type": "string", "required": false, "enum": ["Letter", "LargeLetter", "SmallParcel", "MediumParcel", "Parcel", "Documents"], "description": "Packaging format of the shipment. Requires destinationCountryCode to also be supplied — a 400 is returned otherwise." }, { "name": "packageWeight", "in": "query", "type": "integer", "required": false, "description": "Weight of the package in grams. Requires destinationCountryCode to also be supplied — a 400 is returned otherwise." }, { "name": "carrierGuid", "in": "query", "type": "string", "format": "uuid", "required": false, "description": "GUID of a carrier configured on the account, to scope results to that carrier only. An unrecognised carrierGuid returns a 400. If carrierName is also supplied, both must refer to the same carrier." }, { "name": "carrierName", "in": "query", "type": "string", "required": false, "description": "Name of a carrier configured on the account, to scope results to that carrier only. An unrecognised carrierName returns a 400. If carrierGuid is also supplied, both must refer to the same carrier." } ], "responses": { "200": { "description": "Return list of services grouped by carrier", "schema": { "type": "array", "items": { "$ref": "#/definitions/GetCarrierServicesResource" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] } }, "/services/olp": { "get": { "tags": [ "Olp Services" ], "summary": "List available Royal Mail OLP shipping services", "operationId": "GetOlpShippingServicesAsync", "parameters": [ { "name": "country", "in": "query", "type": "string", "required": true, "description": "ISO 3166-1 alpha-3 destination country code. Must be a recognised ISO 3166-1 alpha-3 code — an unrecognised value returns a 400." }, { "name": "weight", "in": "query", "type": "integer", "required": false, "description": "Package weight in grams." }, { "name": "postcode", "in": "query", "type": "string", "required": false, "description": "Recipient postcode." }, { "name": "packageFormat", "in": "query", "type": "string", "required": false, "enum": ["Letter", "LargeLetter", "SmallParcel", "MediumParcel", "LargeParcel"], "description": "Package format to filter results by. Applied to the results returned by Royal Mail OLP — it isn't sent to Royal Mail OLP itself, which has no equivalent filter on this call." } ], "responses": { "200": { "description": "Lists the available Royal Mail OLP shipping services for the given destination", "schema": { "$ref": "#/definitions/OlpServicesResult" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden (Royal Mail OLP is not configured for this account)" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "503": { "description": "The Royal Mail OLP service is currently unavailable" } }, "security": [ { "Bearer": [] } ] } }, "/orders": { "get": { "tags": [ "Orders" ], "summary": "Retrieve pageable list of orders", "operationId": "GetOrdersAsync", "parameters": [ { "$ref": "#/parameters/pageSize" }, { "$ref": "#/parameters/startDateTime" }, { "$ref": "#/parameters/endDateTime" }, { "$ref": "#/parameters/continuationToken" } ], "responses": { "200": { "description": "Return pageable list of orders", "schema": { "$ref": "#/definitions/GetOrdersResponse" } }, "400": { "description": "Bad Request (Request has missing or invalid parameters and cannot be parsed)", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "Orders" ], "summary": "Create orders", "operationId": "CreateOrdersAsync", "parameters": [ { "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/CreateOrdersRequest" } } ], "responses": { "200": { "description": "Request Processed Successfully", "schema": { "$ref": "#/definitions/CreateOrdersResponse" } }, "400": { "description": "Bad Request (Request has missing or invalid parameters and cannot be parsed)", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] } }, "/orders/full": { "get": { "tags": [ "Orders" ], "summary": "Retrieve pageable list of orders with details", "description": "Reserved for ChannelShipper customers only - please visit ChannelShipper.com for more information", "operationId": "GetOrdersWithDetailsAsync", "parameters": [ { "$ref": "#/parameters/pageSize" }, { "$ref": "#/parameters/startDateTime" }, { "$ref": "#/parameters/endDateTime" }, { "$ref": "#/parameters/continuationToken" } ], "responses": { "200": { "description": "Return a pageable list of orders with details", "schema": { "$ref": "#/definitions/GetOrdersDetailsResponse" } }, "400": { "description": "Bad Request (Request has missing or invalid parameters and cannot be parsed)", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden (Feature not available)" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] } }, "/orders/{orderIdentifiers}/label": { "get": { "tags": [ "Labels" ], "summary": "Return a single PDF file with generated label and/or associated document(s)", "description": "Reserved for OBA customers only\n\nThe account \"Label format\" settings page will control the page format settings used to print the postage label \nand associated documents. Certain combinations of these settings may prevent associated documents from being \nprinted together with the postage label within a single document. If this occurs the documentType option can be \nused in a separate call to print missing documents.\n", "operationId": "GetOrdersLabelAsync", "produces": [ "application/pdf", "application/json" ], "parameters": [ { "$ref": "#/parameters/orderIdentifiers" }, { "$ref": "#/parameters/documentType" }, { "$ref": "#/parameters/includeReturnsLabel" }, { "$ref": "#/parameters/includeCN" }, { "$ref": "#/parameters/includeCommercialInvoice" } ], "responses": { "200": { "description": "Return the PDF file with labels", "schema": { "type": "file" } }, "400": { "description": "Bad Request (Request has missing or invalid parameters and cannot be parsed)", "schema": { "type": "array", "items": { "$ref": "#/definitions/OrderErrorResponse" } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden (Feature available for OBA accounts only)" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] } }, "/manifests": { "post": { "tags": [ "Manifests" ], "summary": "Manifest orders", "description": "For more information on how to manifest orders using the API, including examples of different use-cases please \nvisit either the Click & Drop API Help Page \nor ChannelShipper Help Page.\n", "operationId": "CreateManifestsAsync", "parameters": [ { "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/CreateManifestsRequest" } } ], "responses": { "200": { "description": "Request is valid but no orders eligible for manifesting were found", "schema": { "$ref": "#/definitions/CreateManifestsResponse" } }, "202": { "description": "Request Accepted and manifests are being processed", "schema": { "$ref": "#/definitions/CreateManifestsResponse" } }, "400": { "description": "Bad Request (Request has missing or invalid parameters and cannot be parsed)", "schema": { "$ref": "#/definitions/CreateManifestsErrorResponse" } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden (Feature available for OBA accounts only)" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] } }, "/manifests/{manifestGuid}": { "get": { "tags": [ "Manifests" ], "summary": "Retrieve manifest status and documentation", "operationId": "GetManifestAsync", "parameters": [ { "$ref": "#/parameters/manifestGuid" } ], "responses": { "200": { "description": "Provides information about manifest", "schema": { "$ref": "#/definitions/GetManifestResponse" } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden (Feature available for OBA accounts only)" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] } }, "/manifests/{manifestGuid}/retry": { "post": { "tags": [ "Manifests" ], "summary": "Retry failed manifest", "description": "Request will result in a 400 response if called within 30 mins of a previously failed manifest or retry attempt.", "operationId": "RetryManifestAsync", "parameters": [ { "$ref": "#/parameters/manifestGuid" } ], "responses": { "202": { "description": "Request Accepted and manifest is being processed" }, "400": { "description": "Bad Request (Request has missing or invalid parameters and cannot be parsed)" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden (Feature available for OBA accounts only)" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] } }, "/bulk-customs-consignments": { "post": { "tags": [ "Bulk Customs Consignments" ], "summary": "Create a bulk customs consignment", "operationId": "CreateBulkCustomsConsignment", "parameters": [ { "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/CreateBulkCustomsConsignmentRequest" } } ], "responses": { "201": { "description": "Bulk customs consignment created", "schema": { "$ref": "#/definitions/CreateBulkCustomsConsignmentResponse" } }, "400": { "description": "Bad Request (missing/invalid parameters, or the carrier could not be resolved)", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] } }, "/bulk-customs-consignments/all": { "get": { "tags": [ "Bulk Customs Consignments" ], "summary": "List bulk customs consignments", "operationId": "GetBulkCustomsConsignments", "parameters": [ { "name": "carrierName", "in": "query", "required": false, "type": "string", "maxLength": 50, "description": "Required when the account has more than one active carrier." }, { "name": "status", "in": "query", "required": false, "type": "string", "enum": [ "Open", "Manifested", "InvoiceUploaded" ], "description": "Optional lifecycle status filter. When omitted, all consignments are returned." }, { "name": "page", "in": "query", "required": false, "type": "integer", "minimum": 1, "default": 1 }, { "name": "pageSize", "in": "query", "required": false, "type": "integer", "minimum": 1, "default": 50 } ], "responses": { "200": { "description": "Returns a paginated list of bulk customs consignments", "schema": { "$ref": "#/definitions/GetBulkCustomsConsignmentsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] } }, "/bulk-customs-consignments/{bulkConsignmentIdentifier}": { "get": { "tags": [ "Bulk Customs Consignments" ], "summary": "Get a bulk customs consignment", "operationId": "GetBulkCustomsConsignment", "parameters": [ { "name": "bulkConsignmentIdentifier", "in": "path", "required": true, "type": "string", "maxLength": 20, "description": "The caller-supplied identifier of the bulk customs consignment." }, { "name": "carrierName", "in": "query", "required": false, "type": "string", "maxLength": 50, "description": "Required when the account has more than one active carrier." } ], "responses": { "200": { "description": "Returns the bulk customs consignment", "schema": { "$ref": "#/definitions/GetBulkCustomsConsignmentResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Bulk Customs Consignments" ], "summary": "Delete a bulk customs consignment", "description": "

Permanently deletes the bulk customs consignment. Linked shipments are unlinked, not deleted. A consignment that has already been manifested cannot be deleted.

", "operationId": "DeleteBulkCustomsConsignment", "parameters": [ { "name": "bulkConsignmentIdentifier", "in": "path", "required": true, "type": "string", "maxLength": 20, "description": "The caller-supplied identifier of the bulk customs consignment." }, { "name": "carrierName", "in": "query", "required": false, "type": "string", "maxLength": 50 } ], "responses": { "204": { "description": "Bulk customs consignment deleted" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] } }, "/bulk-customs-consignments/{bulkConsignmentIdentifier}/commercial-invoice": { "post": { "tags": [ "Bulk Customs Consignments" ], "summary": "Upload a commercial invoice for a bulk customs consignment", "description": "

Uploads the commercial invoice (and any supporting documents) for the specified bulk customs consignment. Each document must be a base64-encoded PDF under 2MB.

", "operationId": "UploadCommercialInvoice", "parameters": [ { "name": "bulkConsignmentIdentifier", "in": "path", "required": true, "type": "string", "maxLength": 20, "description": "The caller-supplied identifier of the bulk customs consignment." }, { "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/UploadBulkCustomsCommercialInvoiceRequest" } } ], "responses": { "200": { "description": "Returns whether the commercial invoice was uploaded", "schema": { "$ref": "#/definitions/UploadBulkCustomsCommercialInvoiceResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] } }, "/bulk-customs-consignments/{bulkConsignmentIdentifier}/shipments": { "get": { "tags": [ "Bulk Customs Consignments" ], "summary": "List shipments on a bulk customs consignment", "operationId": "GetBulkCustomsConsignmentShipments", "parameters": [ { "name": "bulkConsignmentIdentifier", "in": "path", "required": true, "type": "string", "maxLength": 20 }, { "name": "carrierName", "in": "query", "required": false, "type": "string", "maxLength": 50, "description": "Required when the account has more than one active carrier." }, { "name": "page", "in": "query", "required": false, "type": "integer", "minimum": 1, "default": 1 }, { "name": "pageSize", "in": "query", "required": false, "type": "integer", "minimum": 1, "default": 25 } ], "responses": { "200": { "description": "Returns a paginated list of shipments on the consignment", "schema": { "$ref": "#/definitions/GetBulkCustomsConsignmentShipmentsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "Bulk Customs Consignments" ], "summary": "Add shipments to a bulk customs consignment", "description": "

Adds one or more orders (by order identifier) to the consignment. Each shipment is processed independently; the response reports the per-shipment outcome.

", "operationId": "AddBulkCustomsConsignmentShipments", "parameters": [ { "name": "bulkConsignmentIdentifier", "in": "path", "required": true, "type": "string", "maxLength": 20 }, { "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/AddBulkCustomsConsignmentShipmentsRequest" } } ], "responses": { "200": { "description": "Returns the per-shipment result of the add operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/BulkCustomsConsignmentShipmentResult" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Bulk Customs Consignments" ], "summary": "Remove shipments from a bulk customs consignment", "operationId": "RemoveBulkCustomsConsignmentShipments", "parameters": [ { "name": "bulkConsignmentIdentifier", "in": "path", "required": true, "type": "string", "maxLength": 20 }, { "name": "orderIdentifiers", "in": "query", "required": true, "type": "string", "description": "One or more order identifiers to remove, separated by semicolon." }, { "name": "carrierName", "in": "query", "required": false, "type": "string", "maxLength": 50, "description": "Required when the account has more than one active carrier." } ], "responses": { "200": { "description": "Returns the per-shipment result of the remove operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/BulkCustomsConsignmentShipmentResult" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "Bearer": [] } ] } } }, "definitions": { "GetVersionResource": { "type": "object", "required": [ "releaseDate" ], "properties": { "commit": { "type": "string" }, "build": { "type": "string" }, "release": { "type": "string" }, "releaseDate": { "type": "string", "format": "date-time" } } }, "ErrorResponse": { "type": "object", "required": [ "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "string" } } }, "GetCarrierResource": { "type": "object", "required": [ "carrierGuid", "carrierName" ], "properties": { "carrierGuid": { "type": "string", "format": "uuid" }, "carrierName": { "type": "string" }, "carrierStatus": { "type": "string" }, "carrierType": { "type": "string" } } }, "GetCarrierServicesResource": { "type": "object", "required": [ "carrierGuid", "carrierName", "services" ], "properties": { "carrierGuid": { "type": "string", "format": "uuid" }, "carrierName": { "type": "string" }, "services": { "type": "array", "items": { "$ref": "#/definitions/GetServiceResource" } } } }, "GetServiceResource": { "type": "object", "required": [ "carrierServiceGuid", "serviceName", "serviceCode" ], "properties": { "carrierServiceGuid": { "type": "string", "format": "uuid" }, "serviceName": { "type": "string" }, "serviceCode": { "type": "string" } } }, "OlpServicesResult": { "type": "object", "properties": { "guidanceText": { "type": "string" }, "services": { "type": "array", "items": { "$ref": "#/definitions/OlpServiceOption" } } } }, "OlpServiceOption": { "type": "object", "properties": { "serviceCode": { "type": "string" }, "serviceName": { "type": "string" }, "brand": { "type": "string", "enum": ["RoyalMail", "Parcelforce"] }, "serviceLevel": { "type": "string" }, "packageFormat": { "type": "string", "enum": ["Letter", "LargeLetter", "SmallParcel", "MediumParcel", "LargeParcel"] }, "minWeightGrams": { "type": "integer" }, "maxWeightGrams": { "type": "integer" }, "cost": { "type": "number" }, "vatCost": { "type": "number" }, "enhancements": { "type": "array", "items": { "type": "string" } }, "dropOffOptions": { "type": "array", "items": { "type": "string", "enum": ["Collection", "PostBox", "ParcelBox", "PostOffice", "Parcelshop", "DeliveryOffice", "ParcelforceDepot"] } } } }, "GetOrderInfoResource": { "type": "object", "required": [ "orderIdentifier", "createdOn" ], "properties": { "orderIdentifier": { "type": "integer" }, "orderReference": { "type": "string" }, "createdOn": { "type": "string", "format": "date-time" }, "orderDate": { "type": "string", "format": "date-time" }, "printedOn": { "type": "string", "format": "date-time" }, "manifestedOn": { "type": "string", "format": "date-time" }, "shippedOn": { "type": "string", "format": "date-time" }, "trackingNumber": { "type": "string" }, "packages": { "type": "array", "items": { "$ref": "#/definitions/CreatePackagesResponse" } } } }, "GetOrdersResponse": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/definitions/GetOrderInfoResource" } }, "continuationToken": { "type": "string" } } }, "GetOrdersDetailsResponse": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/definitions/GetOrderDetailsResource" } }, "continuationToken": { "type": "string" } } }, "UpdateOrderStatusResponse": { "type": "object", "properties": { "updatedOrders": { "type": "array", "items": { "$ref": "#/definitions/UpdatedOrderInfo" } }, "errors": { "type": "array", "items": { "$ref": "#/definitions/OrderUpdateError" } } } }, "UpdatedOrderInfo": { "type": "object", "properties": { "orderIdentifier": { "type": "integer" }, "orderReference": { "type": "string" }, "status": { "type": "string", "description": "Current status of the order" } } }, "DeleteOrdersResource": { "type": "object", "properties": { "deletedOrders": { "type": "array", "items": { "$ref": "#/definitions/DeletedOrderInfo" } }, "errors": { "type": "array", "items": { "$ref": "#/definitions/OrderErrorInfo" } } } }, "DeletedOrderInfo": { "type": "object", "properties": { "orderIdentifier": { "type": "integer" }, "orderReference": { "type": "string" }, "orderInfo": { "type": "string" } } }, "CreateOrdersRequest": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minLength": 1, "items": { "$ref": "#/definitions/CreateOrderRequest" } } } }, "UpdateOrdersStatusRequest": { "type": "object", "properties": { "items": { "type": "array", "minLength": 1, "items": { "$ref": "#/definitions/UpdateOrderStatusRequest" } } } }, "UpdateOrderStatusRequest": { "type": "object", "properties": { "orderIdentifier": { "type": "integer", "format": "int32" }, "orderReference": { "type": "string" }, "status": { "type": "string", "description": "
\n\"despatchedByOtherCourier \": Reserved for ChannelShipper customers only - please visit \nChannelShipper.com for more information\n\n\"new \": This will remove the order from its batch. Order information will not be lost during this process.\n\nPlease be aware labels generated on orders which are then set to \"new\" (reset) are no longer valid \nand must be destroyed. If the order is required to be despatched after setting to \"new\" status, a new \nlabel must be generated to attach to the item.\n\nCancelled label information is automatically shared with Royal Mail Revenue Protection, and should a \ncancelled label be identified on an item in the Royal Mail Network, you will be charged on your account \nand an additional handling fee applied.\n", "enum": [ "new", "despatchedByOtherCourier", "despatched" ] }, "trackingNumber": { "type": "string" }, "despatchDate": { "type": "string", "format": "date-time" }, "shippingCarrier": { "type": "string" }, "shippingService": { "type": "string" } } }, "CreateOrderRequest": { "type": "object", "required": [ "recipient", "orderDate", "subtotal", "shippingCostCharged", "total" ], "properties": { "orderReference": { "type": "string", "maxLength": 40 }, "isRecipientABusiness": { "type": "boolean", "description": "Indicates if the recipient is a business or not. Mandatory for Business senders on orders shipping from Great Britain to Northern Ireland, which require additional information for B2B shipments. (Business senders are OBA accounts and OLP accounts declaring themselves as a Business sender)." }, "recipient": { "$ref": "#/definitions/RecipientDetailsRequest" }, "sender": { "$ref": "#/definitions/SenderDetailsRequest" }, "billing": { "$ref": "#/definitions/BillingDetailsRequest" }, "packages": { "type": "array", "minLength": 0, "items": { "$ref": "#/definitions/ShipmentPackageRequest" } }, "orderDate": { "type": "string", "format": "date-time" }, "plannedDespatchDate": { "type": "string", "format": "date-time" }, "specialInstructions": { "type": "string", "maxLength": 500 }, "subtotal": { "type": "number", "format": "decimal", "multipleOf": 0.01, "maximum": 999999.0, "minimum": 0.0 }, "shippingCostCharged": { "type": "number", "format": "decimal", "multipleOf": 0.01, "maximum": 999999.0, "minimum": 0.0 }, "otherCosts": { "type": "number", "format": "decimal", "multipleOf": 0.01, "maximum": 999999.0, "minimum": 0.0 }, "customsDutyCosts": { "type": "number", "description": "Customs Duty Costs is only supported in DDP (Delivery Duty Paid) services", "format": "decimal", "multipleOf": 0.01, "maximum": 99999.99, "minimum": 0.0 }, "total": { "type": "number", "format": "decimal", "multipleOf": 0.01, "maximum": 999999.0, "minimum": 0.0 }, "currencyCode": { "type": "string", "maxLength": 3 }, "containsDangerousGoods": { "type": "boolean", "description": "Indicates that the package contents contain a dangerous goods item" }, "deliveryTerm": { "type": "string", "description": "Specifies how customs duties, taxes, and handling fees are paid for international shipments.

Accepted values are DDP, IOSS_DDP, DDU_DAP, IOSS_DDU, DTP, IOSS_DTP.

N.B. If no value is provided, the delivery term saved on your account is used, or DDU_DAP if none is saved.

", "maxLength": 20 }, "dangerousGoodsUnCode": { "type": "string", "maxLength": 4, "description": "UN Code of the dangerous goods" }, "dangerousDescription": { "type": "number", "description": "Description of the dangerous goods" }, "dangerousGoodsQuantity": { "type": "number", "description": "Quantity or volume of the dangerous goods" }, "postageDetails": { "$ref": "#/definitions/PostageDetailsRequest" }, "tags": { "type": "array", "items": { "$ref": "#/definitions/TagRequest" } }, "label": { "$ref": "#/definitions/LabelGenerationRequest" }, "exporter": { "$ref": "#/definitions/OrderExporterRequest" } } }, "LabelGenerationRequest": { "type": "object", "description": "Reserved for OBA customers only", "required": [ "includeLabelInResponse" ], "properties": { "includeLabelInResponse": { "type": "boolean" }, "includeCN": { "type": "boolean" }, "includeReturnsLabel": { "type": "boolean" } } }, "TagRequest": { "type": "object", "properties": { "key": { "type": "string", "maxLength": 100 }, "value": { "type": "string", "maxLength": 100 } } }, "RecipientDetailsRequest": { "type": "object", "properties": { "address": { "$ref": "#/definitions/AddressRequest" }, "phoneNumber": { "type": "string", "maxLength": 25 }, "emailAddress": { "type": "string", "maxLength": 254 }, "addressBookReference": { "type": "string", "description": "The presence or not of addressBookReference and a valid recipient address object in the request body will determine which of the following behaviours occur:-

1) addressBookReference provided and a valid recipient address object provided - In addition to the provided recipient address fields being used for the order creation, an existing account Address Book Reference with matching addressBookReference will be overwritten with all provided recipient address fields, including phone and email. If no existing account Address Book Reference with matching addressBookReference can be found then a new one will be created with the provided addressBookReference and address fields, including phone and email.
2) addressBookReference provided and a valid recipient address object not provided - An account Address Book Reference with the provided addressBookReference will be used for the order if it exists.
3) addressBookReference not provided and a valid recipient address object provided - All provided recipient address fields, including phone and email, will be used for the order creation.
4) All other scenarios will result in a validation error.", "maxLength": 100 } } }, "AddressRequest": { "type": "object", "required": [ "addressLine1", "city", "countryCode" ], "properties": { "fullName": { "type": "string", "maxLength": 210 }, "companyName": { "type": "string", "maxLength": 100 }, "addressLine1": { "type": "string", "maxLength": 100 }, "addressLine2": { "type": "string", "maxLength": 100 }, "addressLine3": { "type": "string", "maxLength": 100 }, "city": { "type": "string", "maxLength": 100 }, "county": { "type": "string", "maxLength": 100 }, "postcode": { "type": "string", "maxLength": 20 }, "countryCode": { "type": "string", "maxLength": 3 } } }, "BillingDetailsRequest": { "type": "object", "description": "Billing along with billing.address objects are required in specific case when 'Use shipping address for billing address' setting is set to 'false' and 'Recipient.AddressBookReference' is provided.", "properties": { "address": { "$ref": "#/definitions/AddressRequest" }, "phoneNumber": { "type": "string", "maxLength": 25 }, "emailAddress": { "type": "string", "maxLength": 254 } } }, "SenderDetailsRequest": { "type": "object", "properties": { "tradingName": { "type": "string", "maxLength": 250 }, "phoneNumber": { "type": "string", "maxLength": 25, "description": "

Either phoneNumber or emailAddress is required for USA shipments.

" }, "emailAddress": { "type": "string", "maxLength": 254, "description": "

Either phoneNumber or emailAddress is required for USA shipments.

" } } }, "ShipmentPackageRequest": { "type": "object", "required": [ "weightInGrams", "packageFormatIdentifier" ], "properties": { "weightInGrams": { "type": "integer", "format": "int32", "maximum": 30000.0, "minimum": 1.0 }, "packageFormatIdentifier": { "type": "string", "description": "If you have a ChannelShipper account, you can also pass the name of any of your custom package formats instead of the values below.
Enum: 'undefined', 'letter', 'largeLetter', 'smallParcel', 'mediumParcel', 'largeParcel', 'parcel', 'documents'" }, "customPackageFormatIdentifier": { "type": "string", "description": "This field will be deprecated in the future. Please use 'packageFormatIdentifier' for custom package formats from ChannelShipper." }, "dimensions": { "$ref": "#/definitions/DimensionsRequest" }, "contents": { "type": "array", "minLength": 0, "items": { "$ref": "#/definitions/ProductItemRequest" } } } }, "PostageDetailsRequest": { "type": "object", "example": { "sendNotificationsTo": "sender", "serviceCode": "string", "serviceRegisterCode": "st", "consequentialLoss": "0", "receiveEmailNotification": "true", "receiveSmsNotification": "true", "guaranteedSaturdayDelivery": "false", "requestSignatureUponDelivery": "true", "isLocalCollect": "true", "safePlace": "string", "department": "string", "AIRNumber": "string", "IOSSNumber": "string", "requiresExportLicense": "true", "commercialInvoiceNumber": "string", "commercialInvoiceDate": "2019-08-24T14:15:22Z", "recipientEoriNumber": "string" }, "properties": { "sendNotificationsTo": { "type": "string", "enum": [ "sender", "recipient", "billing" ] }, "serviceCode": { "type": "string", "maxLength": 10 }, "carrierName": { "type": "string", "maxLength": 50 }, "serviceRegisterCode": { "type": "string", "maxLength": 2 }, "consequentialLoss": { "type": "integer", "format": "int32", "maximum": 10000.0, "minimum": 0.0 }, "receiveEmailNotification": { "type": "boolean" }, "receiveSmsNotification": { "type": "boolean" }, "guaranteedSaturdayDelivery": { "type": "boolean", "description": "This field has been deprecated" }, "requestSignatureUponDelivery": { "type": "boolean" }, "isLocalCollect": { "type": "boolean" }, "safePlace": { "type": "string", "maxLength": 90 }, "department": { "type": "string", "maxLength": 150 }, "AIRNumber": { "type": "string", "maxLength": 50, "description": "For B2B orders shipping from Great Britain to Northern Ireland, this field can be used to provide the Recipient UKIMs number." }, "IOSSNumber": { "type": "string", "maxLength": 50 }, "requiresExportLicense": { "type": "boolean" }, "commercialInvoiceNumber": { "type": "string", "maxLength": 35 }, "commercialInvoiceDate": { "type": "string", "format": "date-time" }, "recipientEoriNumber": { "type": "string" } } }, "ProductItemRequest": { "type": "object", "required": [ "quantity" ], "properties": { "name": { "type": "string", "maxLength": 800 }, "SKU": { "type": "string", "description": "The presence or not of field SKU and other fields in the request body will determine which of the following behaviours occur:-
1) A minimum of SKU, unitValue, unitWeightInGrams and quantity provided - In addition to the provided product fields being used for the order creation, an existing account Product with matching SKU will be overwritten with all provided product parameters. If no existing account Product with matching SKU can be found then a new product will be created with the provided SKU and product parameters.
2) SKU, quantity provided and no other fields provided - An account Product with the provided SKU will be used for the order if it exists.
3) SKU not provided and a minimum of unitValue, unitWeightInGrams and quantity provided - All provided product fields will be used for the order creation.
4) All other scenarios will result in a validation error.

Required for EU shipments on items declared as eCommerceSaleOfGoods or commercialSaleOfGoods

", "maxLength": 100 }, "ReferenceId": { "type": "string", "description": "The non-standardised manufacturer's product reference code for the item. This field will be deprecated in the future. Please use 'NonStandardisedManufacturerId' instead.", "maxLength": 50 }, "ContentsPieceURL": { "type": "string", "description": "A URL linking directly to the specific product page for the item being shipped. Must point to an individual product listing, not a general shop homepage or category page.", "maxLength": 250 }, "NonStandardisedManufacturerId": { "type": "string", "description": "The non-standardised manufacturer's product reference code for the item.

Required for EU shipments on items declared as eCommerceSaleOfGoods or commercialSaleOfGoods

", "maxLength": 50 }, "StandardisedManufacturerId": { "type": "string", "description": "The standardised manufacturer's product reference code for the item (e.g. GTIN, EAN, UPC).

If NonStandardisedManufacturerId isn't provided, this value is also used as the NonStandardisedManufacturerId.

", "maxLength": 50 }, "PgaReferenceNumber": { "type": "string", "description": "The PGA (Partner Government Agency) reference number for the item. Can only contain A-Z, 0-9, spaces, full stops, hyphens and forward slashes.

USA Shipments only

", "maxLength": 50 }, "quantity": { "type": "integer", "format": "int32", "maximum": 999999.0, "minimum": 1.0 }, "unitValue": { "type": "number", "format": "decimal", "multipleOf": 0.01, "maximum": 999999.0, "minimum": 0.0 }, "unitWeightInGrams": { "type": "integer", "maximum": 999999.0, "minimum": 0.0 }, "customsDescription": { "type": "string", "maxLength": 50 }, "extendedCustomsDescription": { "type": "string", "maxLength": 300 }, "customsCode": { "type": "string", "maxLength": 10 }, "originCountryCode": { "type": "string", "maxLength": 3 }, "customsDeclarationCategory": { "type": "string", "enum": [ "none", "gift", "commercialSample", "documents", "other", "returnedGoods", "saleOfGoods", "mixedContent" ] }, "requiresExportLicence": { "type": "boolean" } } }, "DimensionsRequest": { "type": "object", "description": "It is not mandatory to include the dimensions field. If the dimensions field is included then the inner fields heightInMms, widthInMms and depthInMms must be specified with non-zero values.", "required": [ "heightInMms", "widthInMms", "depthInMms" ], "properties": { "heightInMms": { "type": "integer", "format": "int32" }, "widthInMms": { "type": "integer", "format": "int32" }, "depthInMms": { "type": "integer", "format": "int32" } } }, "OrderExporterRequest": { "type": "object", "properties": { "addressLine1": { "type": "string", "maxLength": 250 }, "addressLine2": { "type": "string", "maxLength": 250 }, "addressLine3": { "type": "string", "maxLength": 250 }, "city": { "type": "string", "maxLength": 100 }, "postcode": { "type": "string", "maxLength": 20 }, "country": { "type": "string", "maxLength": 200 }, "businessName": { "type": "string", "maxLength": 150 }, "contactName": { "type": "string", "maxLength": 150 }, "phoneNumber": { "type": "string", "maxLength": 25 }, "emailAddress": { "type": "string", "maxLength": 254 }, "vatNumber": { "type": "string", "maxLength": 50 }, "eoriNumber": { "type": "string", "maxLength": 18 } } }, "CreateOrdersResponse": { "type": "object", "properties": { "successCount": { "type": "integer" }, "errorsCount": { "type": "integer" }, "createdOrders": { "type": "array", "items": { "$ref": "#/definitions/CreateOrderResponse" } }, "failedOrders": { "type": "array", "items": { "$ref": "#/definitions/FailedOrderResponse" } } } }, "CreateOrderResponse": { "type": "object", "required": [ "orderIdentifier", "createdOn" ], "properties": { "orderIdentifier": { "type": "integer" }, "orderReference": { "type": "string" }, "createdOn": { "type": "string", "format": "date-time" }, "orderDate": { "type": "string", "format": "date-time" }, "printedOn": { "type": "string", "format": "date-time" }, "manifestedOn": { "type": "string", "format": "date-time" }, "shippedOn": { "type": "string", "format": "date-time" }, "trackingNumber": { "type": "string" }, "packages": { "type": "array", "items": { "$ref": "#/definitions/CreatePackagesResponse" } }, "label": { "type": "string", "description": "label in format base64 string" }, "labelErrors": { "type": "array", "items": { "$ref": "#/definitions/CreateOrderLabelErrorResponse" } }, "generatedDocuments": { "type": "array", "items": { "type": "string" } } } }, "FailedOrderResponse": { "type": "object", "properties": { "order": { "$ref": "#/definitions/CreateOrderRequest" }, "errors": { "type": "array", "items": { "$ref": "#/definitions/CreateOrderErrorResponse" } } } }, "CreateOrderErrorResponse": { "type": "object", "properties": { "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "fields": { "type": "array", "items": { "$ref": "#/definitions/OrderFieldResponse" } } } }, "OrderErrorResponse": { "type": "object", "properties": { "accountOrderNumber": { "type": "integer" }, "channelOrderReference": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } }, "OrderErrorInfo": { "type": "object", "properties": { "orderIdentifier": { "type": "integer" }, "orderReference": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } }, "OrderUpdateError": { "type": "object", "properties": { "orderIdentifier": { "type": "integer" }, "orderReference": { "type": "string" }, "status": { "type": "string", "description": "Current status of the order" }, "code": { "type": "string" }, "message": { "type": "string" } } }, "CreatePackagesResponse": { "type": "object", "properties": { "packageNumber": { "type": "integer" }, "trackingNumber": { "type": "string" } } }, "CreateOrderLabelErrorResponse": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } } }, "OrderFieldResponse": { "type": "object", "properties": { "fieldName": { "type": "string" }, "value": { "type": "string" } } }, "GetOrderDetailsResource": { "type": "object", "required": [ "subtotal", "shippingCostCharged", "orderDiscount", "total", "weightInGrams", "shippingDetails", "shippingInfo", "billingInfo", "orderLines" ], "properties": { "orderIdentifier": { "type": "integer" }, "orderStatus": { "type": "string" }, "createdOn": { "type": "string", "format": "date-time" }, "printedOn": { "type": "string", "format": "date-time" }, "shippedOn": { "type": "string", "format": "date-time" }, "postageAppliedOn": { "type": "string", "format": "date-time" }, "manifestedOn": { "type": "string", "format": "date-time" }, "orderDate": { "type": "string", "format": "date-time" }, "despatchedByOtherCourierOn": { "type": "string", "format": "date-time" }, "tradingName": { "type": "string" }, "channel": { "type": "string" }, "marketplaceTypeName": { "type": "string" }, "department": { "type": "string" }, "AIRNumber": { "type": "string" }, "requiresExportLicense": { "type": "boolean" }, "commercialInvoiceNumber": { "type": "string" }, "commercialInvoiceDate": { "type": "string", "format": "date-time" }, "orderReference": { "type": "string" }, "channelShippingMethod": { "type": "string" }, "specialInstructions": { "type": "string" }, "pickerSpecialInstructions": { "type": "string" }, "subtotal": { "type": "number" }, "shippingCostCharged": { "type": "number" }, "orderDiscount": { "type": "number" }, "total": { "type": "number" }, "weightInGrams": { "type": "integer" }, "packageSize": { "type": "string" }, "accountBatchNumber": { "type": "string" }, "currencyCode": { "type": "string", "maxLength": 3 }, "shippingDetails": { "$ref": "#/definitions/GetShippingDetailsResult" }, "shippingInfo": { "$ref": "#/definitions/GetPostalDetailsResult" }, "billingInfo": { "$ref": "#/definitions/GetPostalDetailsResult" }, "orderLines": { "type": "array", "items": { "$ref": "#/definitions/GetOrderLineResult" } }, "tags": { "type": "array", "items": { "$ref": "#/definitions/GetTagDetailsResult" } } } }, "GetShippingDetailsResult": { "type": "object", "required": [ "shippingCost" ], "properties": { "shippingCost": { "type": "number" }, "trackingNumber": { "type": "string" }, "shippingTrackingStatus": { "type": "string" }, "serviceCode": { "type": "string" }, "shippingService": { "type": "string" }, "shippingCarrier": { "type": "string" }, "receiveEmailNotification": { "type": "boolean" }, "receiveSmsNotification": { "type": "boolean" }, "guaranteedSaturdayDelivery": { "type": "boolean" }, "requestSignatureUponDelivery": { "type": "boolean" }, "isLocalCollect": { "type": "boolean" }, "shippingUpdateSuccessDate": { "type": "string", "format": "date-time" }, "packages": { "type": "array", "items": { "$ref": "#/definitions/CreatePackagesResponse" } } } }, "GetPostalDetailsResult": { "type": "object", "properties": { "title": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "companyName": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "addressLine3": { "type": "string" }, "city": { "type": "string" }, "county": { "type": "string" }, "postcode": { "type": "string" }, "countryCode": { "type": "string", "maxLength": 3 }, "phoneNumber": { "type": "string" }, "emailAddress": { "type": "string" } } }, "GetTagDetailsResult": { "type": "object", "properties": { "key": { "type": "string", "maxLength": 100 }, "value": { "type": "string", "maxLength": 100 } } }, "GetOrderLineResult": { "type": "object", "required": [ "quantity" ], "properties": { "SKU": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "integer" }, "unitValue": { "type": "number" }, "lineTotal": { "type": "number" }, "customsCode": { "type": "string" } } }, "CreateManifestsRequest": { "type": "object", "properties": { "carrierName": { "type": "string", "description": "The name of the carrier you would like to manifest orders for. This is required if the account has multiple carriers or multiple postage location numbers, and must match the name configured in the carrier settings within the main website.", "maxLength": 50 }, "skipPaperwork": { "type": "boolean", "description": "Optional. Set to true to manifest without generating the customs paperwork. Defaults to false." }, "bulkCustomsConsignmentIdentifier": { "type": "string", "maxLength": 20, "description": "Optional. The identifier of the bulk customs consignment (BCC) to manifest. When supplied, only the shipments on that BCC are manifested together in a single operation; the BCC must have a commercial invoice uploaded and all shipments in a manifestable state, otherwise the request is rejected. When omitted, shipments belonging to any BCC are excluded from the manifest run." } } }, "CreateManifestsResponse": { "type": "object", "properties": { "manifests": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "CreateManifestsErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/CreateManifestsError" } } } }, "CreateManifestsError": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "orderIdentifier": { "type": "integer" }, "orderReference": { "type": "string" }, "accountBatchNumber": { "type": "string", "pattern": "^B\\d{1,10}$" } } }, "GetManifestResponse": { "type": "object", "properties": { "manifestStatus": { "type": "string", "description": "* InProgress: Manifest operation is currently in progress\n* Completed: Manifest operation has been completed\n* Failed: Manifest operation has failed\n", "enum": [ "InProgress", "Completed", "Failed" ] }, "documentStatus": { "type": "string", "description": "* InProgress: Manifest documentation generation is currently in progress\n* Completed: Manifest documentation generation has been completed\n", "enum": [ "InProgress", "Completed" ] }, "errorReference": { "type": "string", "format": "uuid" }, "orders": { "type": "array", "items": { "$ref": "#/definitions/GetManifestOrder" } }, "pdf": { "type": "string", "description": "pdf file encoded as base64 format string" } } }, "GetManifestOrder": { "type": "object", "properties": { "orderIdentifier": { "type": "integer" }, "orderReference": { "type": "string" } } }, "CreateBulkCustomsConsignmentRequest": { "type": "object", "required": [ "bulkCustomsConsignmentIdentifier", "recipientCountryCode", "currencyCode", "customsDeclarationCategory", "exporter", "importer" ], "properties": { "carrierName": { "type": "string", "maxLength": 50, "description": "Required when the account has more than one active carrier." }, "bulkCustomsConsignmentIdentifier": { "type": "string", "maxLength": 20, "description": "Caller-supplied reference. Must be unique per account." }, "recipientCountryCode": { "type": "string", "maxLength": 3, "description": "ISO 3-character (alpha-3) destination country code, e.g. \"USA\"." }, "currencyCode": { "type": "string", "maxLength": 3, "description": "Currency code, e.g. \"GBP\"." }, "customsDeclarationCategory": { "type": "string", "enum": [ "EcommerceSaleOfGoods", "CommercialSaleOfGoods" ] }, "exporter": { "$ref": "#/definitions/BulkCustomsConsignmentExporterDetails" }, "importer": { "$ref": "#/definitions/BulkCustomsConsignmentImporterDetails" } } }, "BulkCustomsConsignmentImporterDetails": { "type": "object", "properties": { "addressLine1": { "type": "string", "maxLength": 250 }, "addressLine2": { "type": "string", "maxLength": 250 }, "addressLine3": { "type": "string", "maxLength": 250 }, "companyName": { "type": "string", "maxLength": 150 }, "city": { "type": "string", "maxLength": 100 }, "postcode": { "type": "string", "maxLength": 25 }, "countryCode": { "type": "string", "maxLength": 3, "description": "ISO 3-character (alpha-3) country code." }, "businessName": { "type": "string", "maxLength": 150 }, "contactName": { "type": "string", "maxLength": 150 }, "phoneNumber": { "type": "string", "maxLength": 25 }, "emailAddress": { "type": "string", "maxLength": 254 }, "vatNumber": { "type": "string", "maxLength": 50 }, "eoriNumber": { "type": "string", "maxLength": 18 } } }, "BulkCustomsConsignmentExporterDetails": { "type": "object", "properties": { "addressLine1": { "type": "string", "maxLength": 250 }, "addressLine2": { "type": "string", "maxLength": 250 }, "addressLine3": { "type": "string", "maxLength": 250 }, "city": { "type": "string", "maxLength": 100 }, "postcode": { "type": "string", "maxLength": 25 }, "countryCode": { "type": "string", "maxLength": 3, "description": "ISO 3-character (alpha-3) country code." }, "businessName": { "type": "string", "maxLength": 150 }, "contactName": { "type": "string", "maxLength": 150 }, "phoneNumber": { "type": "string", "maxLength": 25 }, "emailAddress": { "type": "string", "maxLength": 254 }, "vatNumber": { "type": "string", "maxLength": 50 }, "eoriNumber": { "type": "string", "maxLength": 18 } } }, "CreateBulkCustomsConsignmentResponse": { "type": "object", "properties": { "bulkCustomsConsignmentGuid": { "type": "string", "format": "uuid", "description": "System-generated GUID. Use this in all subsequent calls." }, "bulkCustomsConsignmentIdentifier": { "type": "string" } } }, "GetBulkCustomsConsignmentResponse": { "type": "object", "properties": { "bulkCustomsConsignmentGuid": { "type": "string", "format": "uuid" }, "bulkCustomsConsignmentIdentifier": { "type": "string" }, "shipmentCount": { "type": "integer" }, "isManifested": { "type": "boolean" }, "isCommercialInvoiceUploaded": { "type": "boolean" }, "createdOn": { "type": "string", "format": "date-time" }, "customsDeclarationCategory": { "type": "string" }, "recipientCountryCode": { "type": "string" }, "currencyCode": { "type": "string" }, "exporter": { "$ref": "#/definitions/BulkCustomsConsignmentExporterDetails" }, "importer": { "$ref": "#/definitions/BulkCustomsConsignmentImporterDetails" } } }, "GetBulkCustomsConsignmentsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/GetBulkCustomsConsignmentResponse" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" } } }, "AddBulkCustomsConsignmentShipmentsRequest": { "type": "object", "required": [ "orderIdentifiers" ], "properties": { "carrierName": { "type": "string", "maxLength": 50, "description": "Required when the account has more than one active carrier." }, "orderIdentifiers": { "type": "array", "items": { "type": "string" }, "description": "The order identifiers to add to the consignment." } } }, "BulkCustomsConsignmentShipmentResult": { "type": "object", "properties": { "orderIdentifier": { "type": "string" }, "shipmentGuid": { "type": "string", "format": "uuid" }, "isSuccessful": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } } } }, "BulkCustomsConsignmentShipmentSummary": { "type": "object", "properties": { "shipmentGuid": { "type": "string", "format": "uuid" }, "orderIdentifier": { "type": "string" }, "trackingNumber": { "type": "string" }, "isManifested": { "type": "booleanaddressLine1" } } }, "GetBulkCustomsConsignmentShipmentsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/BulkCustomsConsignmentShipmentSummary" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" } } }, "UploadBulkCustomsCommercialInvoiceRequest": { "type": "object", "required": [ "commercialInvoice" ], "properties": { "carrierName": { "type": "string", "maxLength": 50, "description": "Required when the account has more than one active carrier." }, "commercialInvoice": { "type": "string", "description": "Commercial invoice encoded as a base64 PDF string, under 2MB." }, "supportingDocuments": { "type": "array", "items": { "type": "string" }, "description": "Optional supporting documents, each encoded as a base64 PDF string under 2MB." } } }, "UploadBulkCustomsCommercialInvoiceResponse": { "type": "object", "properties": { "isUploaded": { "type": "boolean" } } } }, "parameters": { "orderIdentifiers": { "type": "string", "name": "orderIdentifiers", "in": "path", "required": true, "description": "One or several Order Identifiers or Order References separated by semicolon. Order Identifiers are integer numbers. Order References are strings - each must be percent-encoded and surrounded by double quotation marks. The maximum number of identifiers is 100.", "example": "/orders/\"ref\";1001;\"Reference%3BWith%3BSpecial%3BSymbols!\";2345/" }, "includeCN": { "type": "boolean", "name": "includeCN", "in": "query", "description": "Include CN22/CN23 with label. Optional parameter. If this parameter is used the setting will override the default account behaviour specified in the \"Label format\" setting \"Generate customs declarations with orders\"" }, "includeReturnsLabel": { "type": "boolean", "name": "includeReturnsLabel", "in": "query", "description": "Include returns label. Required when documentType is set to 'postageLabel'" }, "includeCommercialInvoice": { "type": "boolean", "name": "includeCommercialInvoice", "in": "query", "description": "Include commercial invoice with label. Optional parameter" }, "documentType": { "type": "string", "name": "documentType", "in": "query", "required": true, "description": "Document generation mode. When documentType is set to \"postageLabel\" the additional parameters below must be used. These additional parameters will be ignored when documentType is not set to \"postageLabel\"", "enum": [ "postageLabel", "despatchNote", "CN22", "CN23", "commercialInvoice" ] }, "manifestGuid": { "type": "string", "name": "manifestGuid", "in": "path", "required": true, "description": "GUID of manifest", "format": "uuid" }, "page": { "type": "integer", "name": "page", "in": "query", "description": "The number of page to return", "default": "1", "maximum": 100.0, "minimum": 1.0 }, "pageSize": { "type": "integer", "name": "pageSize", "in": "query", "description": "The number of items to return", "default": "25", "maximum": 100.0, "minimum": 1.0 }, "startDateTime": { "type": "string", "name": "startDateTime", "in": "query", "description": "Date and time lower bound for items filtering", "format": "date-time" }, "endDateTime": { "type": "string", "name": "endDateTime", "in": "query", "description": "Date and time upper bound for items filtering", "format": "date-time" }, "continuationToken": { "type": "string", "name": "continuationToken", "in": "query", "description": "The token for retrieving the next page of items" } }, "securityDefinitions": { "Bearer": { "type": "apiKey", "description": "Authorization header using the Bearer scheme.\r\n\r\nEnter 'Bearer' [space] and then your token in the text input below.\r\n\r\nExample: 'Bearer 12345abcdef'", "name": "Authorization", "in": "header" } }, "tags": [ { "name": "Rate Limits", "description": "

Exceeding the rate limit of 5 calls per second will result in a 429 error.

" }, { "name": "Version" }, { "name": "Orders" }, { "name": "Labels" }, { "name": "Bulk Customs Consignments", "description": "

Reserved for OBA customers only

Group multiple international shipments into a single bulk customs consignment, then manage the shipments within it.

" } ] }