{ "openapi": "3.1.0", "info": { "title": "ShipBG API", "version": "v1", "description": "ShipBG multi-carrier shipping aggregation API. Integer monetary request fields use ISO 4217 minor units (for example, 100.01 BGN is 10001). See https:\/\/github.com\/SK-Software-Ltd\/shipbg for source." }, "servers": [ { "url": "https:\/\/backend-zhorzh.tunnel.shipbg.com\/api\/v1", "description": "Local (backend-zhorzh.tunnel.shipbg.com)" }, { "url": "https:\/\/shipbg.com\/api\/v1", "description": "Production" }, { "url": "https:\/\/staging.shipbg.com\/api\/v1", "description": "Staging" } ], "paths": { "\/account": { "get": { "operationId": "v1.account.show", "description": "Returns the account, subscription, usage, and contract-specific integration metadata visible to the authenticated client.", "summary": "Get the current account", "tags": [ "Account" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "$ref": "#\/components\/schemas\/Account202607Resource" }, { "$ref": "#\/components\/schemas\/Account20260806Resource" } ] } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/account\/email\/request-change": { "post": { "operationId": "v1.account.email.request-change", "description": "Starts the verified account-email change flow and reports where the confirmation was sent.", "summary": "Request an email change", "tags": [ "Account" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "new_email": { "type": "string", "format": "email", "maxLength": 255 } }, "required": [ "new_email" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/EmailChangeRequestResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/account\/email\/confirm-change": { "post": { "operationId": "v1.account.email.confirm-change", "description": "Consumes the email-change confirmation token and returns the newly active account email.", "summary": "Confirm an email change", "tags": [ "Account" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 10 } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/EmailChangeConfirmationResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/account\/profile": { "patch": { "operationId": "v1.account.profile.update", "description": "Updates the authenticated user profile fields and returns the saved public profile.", "summary": "Update the account profile", "tags": [ "Account" ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 255 } } } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AccountProfileResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/addresses:normalize": { "post": { "operationId": "v1.addresses.normalize", "description": "Parses a free-form or structured address into normalized fields suitable for carrier requests.", "summary": "Normalize a shipping address", "tags": [ "AddressNormalize" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/NormalizeAddressCommand" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/NormalizedAddressResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/auth\/tokens": { "post": { "operationId": "v1.auth.tokens.store", "description": "Authenticates an account and returns a bearer token once; store the token securely because it cannot be retrieved again.", "summary": "Create an API token", "tags": [ "AuthTokens" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 }, "password": { "type": "string", "maxLength": 255 }, "device_name": { "type": "string", "maxLength": 255 }, "domain_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "email", "password", "device_name" ] } } } }, "responses": { "200": { "description": "`ApiTokenResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiTokenResource" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "429": { "$ref": "#\/components\/responses\/ThrottleRequestsException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/auth\/tokens\/exchange": { "post": { "operationId": "v1.auth.tokens.exchange", "description": "Exchanges a short-lived Connect authorization token for a long-lived integration bearer token.", "summary": "Exchange a Connect token", "tags": [ "AuthTokens" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "exchange_token": { "type": "string", "maxLength": 255 }, "device_name": { "type": "string", "maxLength": 255 } }, "required": [ "exchange_token", "device_name" ] } } } }, "responses": { "200": { "description": "`ApiTokenResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiTokenResource" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "429": { "$ref": "#\/components\/responses\/ThrottleRequestsException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/auth\/tokens\/{token}": { "delete": { "operationId": "v1.auth.tokens.destroy", "description": "Revokes the named token owned by the authenticated user and returns no response body.", "summary": "Revoke an API token", "tags": [ "AuthTokens" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content", "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/geocode\/autocomplete": { "get": { "operationId": "v1.geocode.autocomplete", "description": "Returns typed address suggestions for the supplied partial query and optional geographic constraints.", "summary": "Autocomplete an address", "tags": [ "AutocompleteAddress" ], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 255 } }, { "name": "country", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AutocompleteAddressResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/shipments:bulk-generate-labels": { "post": { "operationId": "v1.shipments.bulk-generate-labels", "description": "Queues label generation for multiple shipments and returns an asynchronous batch to poll.", "summary": "Generate labels in bulk", "tags": [ "BulkBatches" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "shipment_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 } }, "required": [ "shipment_ids" ] } } } }, "responses": { "202": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/BulkBatchResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/shipments:bulk-cancel": { "post": { "operationId": "v1.shipments.bulk-cancel", "description": "Queues cancellation for multiple shipments and returns an asynchronous batch to poll.", "summary": "Cancel shipments in bulk", "tags": [ "BulkBatches" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "shipment_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 } }, "required": [ "shipment_ids" ] } } } }, "responses": { "202": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/BulkBatchResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/bulk-batches\/{bulkBatch}": { "get": { "operationId": "v1.bulk-batches.show", "description": "Returns batch progress and per-shipment results when processing has produced them.", "summary": "Get a bulk batch", "tags": [ "BulkBatches" ], "parameters": [ { "name": "bulkBatch", "in": "path", "required": true, "description": "The bulk batch ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/BulkBatchResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/bulk-batches\/{bulkBatch}\/labels": { "get": { "operationId": "v1.bulk-batches.labels", "description": "Downloads the completed batch labels as one PDF document.", "summary": "Download merged bulk labels", "tags": [ "BulkBatches" ], "parameters": [ { "name": "bulkBatch", "in": "path", "required": true, "description": "The bulk batch ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application\/pdf": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Content-Disposition": { "schema": { "type": "string" } }, "Content-Length": { "schema": { "type": "string" } }, "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/carrier-accounts\/defaults": { "get": { "operationId": "v1.carrier-accounts.defaults", "description": "Returns the effective non-secret sender and service defaults keyed by connected carrier.", "summary": "Get carrier account defaults", "tags": [ "CarrierAccounts" ], "parameters": [ { "name": "environment", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`CarrierAccountDefaultsResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CarrierAccountDefaultsResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/carrier-accounts\/test": { "post": { "operationId": "v1.carrier-accounts.test", "description": "Validates supplied carrier credentials without storing or returning the credential values.", "summary": "Test carrier credentials", "tags": [ "CarrierAccounts" ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TestCarrierConnectionCommand" } } } }, "responses": { "200": { "description": "`CarrierConnectionTestResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CarrierConnectionTestResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/carrier-accounts\/{courierAccount}\/discovery": { "get": { "operationId": "v1.carrier-accounts.discovery", "description": "Returns carrier-defined contracts, services, agreements, or other selectable values for one connected account.", "summary": "Discover carrier account options", "tags": [ "CarrierAccounts" ], "parameters": [ { "name": "courierAccount", "in": "path", "required": true, "description": "The courier account ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`CarrierDiscoveryResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CarrierDiscoveryResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/carrier-accounts\/{courierAccount}\/capabilities": { "get": { "operationId": "v1.carrier-accounts.capabilities", "description": "Returns the live carrier-specific capabilities available through one connected account.", "summary": "Get carrier account capabilities", "tags": [ "CarrierAccounts" ], "parameters": [ { "name": "courierAccount", "in": "path", "required": true, "description": "The courier account ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CarrierCapabilitiesResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/carrier-accounts": { "get": { "operationId": "v1.carrier-accounts.index", "description": "Lists connected carrier accounts and safe public settings without ever exposing stored credentials.", "summary": "List carrier accounts", "tags": [ "CarrierAccounts" ], "responses": { "200": { "description": "`CarrierAccountListResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CarrierAccountListResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } }, "post": { "operationId": "v1.carrier-accounts.store", "description": "Stores a merchant-owned carrier connection and returns its credential-safe public representation.", "summary": "Connect a carrier account", "tags": [ "CarrierAccounts" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateCarrierAccountCommand" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CarrierAccountResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/carrier-accounts\/{courierAccount}": { "get": { "operationId": "v1.carrier-accounts.show", "description": "Returns one connected carrier account without stored credential values.", "summary": "Get a carrier account", "tags": [ "CarrierAccounts" ], "parameters": [ { "name": "courierAccount", "in": "path", "required": true, "description": "The courier account ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CarrierAccountResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } }, "put": { "operationId": "v1.carrier-accounts.update", "description": "Updates connection settings or credentials and returns the credential-safe public representation.", "summary": "Update a carrier account", "tags": [ "CarrierAccounts" ], "parameters": [ { "name": "courierAccount", "in": "path", "required": true, "description": "The courier account ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateCarrierAccountCommand" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CarrierAccountResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } }, "delete": { "operationId": "v1.carrier-accounts.destroy", "description": "Deletes one connected carrier account and returns no response body.", "summary": "Delete a carrier account", "tags": [ "CarrierAccounts" ], "parameters": [ { "name": "courierAccount", "in": "path", "required": true, "description": "The courier account ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content", "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/carrier-routing": { "get": { "operationId": "v1.carrier-routing.show", "description": "Returns carrier priority and enablement for address, office, and locker deliveries.", "summary": "Get carrier routing", "tags": [ "CarrierRouting" ], "parameters": [ { "name": "domain_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`CarrierRoutingResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CarrierRoutingResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } }, "put": { "operationId": "v1.carrier-routing.update", "description": "Replaces the carrier routing matrix and reports any configuration warnings.", "summary": "Update carrier routing", "tags": [ "CarrierRouting" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateCarrierRoutingCommand" } } } }, "responses": { "200": { "description": "`CarrierRoutingResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CarrierRoutingResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/carriers\/verification-destinations": { "get": { "operationId": "v1.carriers.verification-destinations.index", "description": "Returns safe test recipients and destinations that can be used when verifying carrier connections.", "summary": "List verification destinations", "tags": [ "CarrierVerificationDestinations" ], "parameters": [ { "name": "carriers", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`CarrierVerificationDestinationsResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CarrierVerificationDestinationsResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/carriers": { "get": { "operationId": "v1.carriers.index", "description": "Returns the carrier catalog, connection fields, delivery types, label formats, and supported features.", "summary": "List supported carriers", "tags": [ "Carriers" ], "responses": { "200": { "description": "`CarrierManifestResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CarrierManifestResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/checkout\/options": { "post": { "operationId": "v1.checkout.options", "description": "Quotes and ranks live home and pickup choices for checkout, including prices, pickup points, applied pricing rules, and per-carrier errors.", "summary": "Build checkout delivery options", "tags": [ "Checkout" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/BuildCheckoutOptionsCommand" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CheckoutOptionsResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/carriers\/econt\/address:validate": { "post": { "operationId": "v1.carriers.econt.address-validate", "description": "Validates and parses a Bulgarian address through the connected Econt account.", "summary": "Validate an Econt address", "tags": [ "EcontAddressValidate" ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "city": { "type": "string", "default": "" }, "postcode": { "type": "string", "default": "" }, "country": { "type": "string", "default": "BG" }, "address_line1": { "type": "string", "default": "" }, "address_line2": { "type": "string", "default": "" } } } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/EcontAddressValidationResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/MessageResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "422": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/MessageResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" } } } }, "\/carriers\/econt\/nomenclature": { "get": { "operationId": "v1.carriers.econt.nomenclature", "description": "Searches Econt cities, streets, or quarters and returns their carrier-native identifiers.", "summary": "Search Econt nomenclature", "tags": [ "EcontNomenclature" ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "city_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/EcontNomenclatureResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "422": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/MessageResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/MessageResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" } } } }, "\/geocode": { "post": { "operationId": "v1.geocode", "description": "Resolves an address to geographic coordinates and reports the normalized display label.", "summary": "Geocode an address", "tags": [ "Geocode" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/GeocodeAddressCommand" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/GeocodeResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/health": { "get": { "operationId": "v1.health", "description": "Returns the deployed version and health of critical dependencies; degraded critical services produce the same typed body with status 503.", "summary": "Check API health", "tags": [ "Health" ], "responses": { "200": { "description": "`HealthResponseResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/HealthResponseResource" } } } }, "503": { "description": "A critical backend dependency is degraded.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/HealthResponseResource" } } } }, "429": { "$ref": "#\/components\/responses\/ThrottleRequestsException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/hs-codes": { "get": { "operationId": "v1.hs-codes.index", "description": "Searches harmonized-system commodity codes with localized descriptions and pagination metadata.", "summary": "Search HS codes", "tags": [ "HsCodes" ], "parameters": [ { "name": "version", "in": "query", "schema": { "type": "string" } }, { "name": "source", "in": "query", "schema": { "type": "string" } }, { "name": "jurisdiction", "in": "query", "schema": { "type": "string" } }, { "name": "leaf_only", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "`HsCodeSearchResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/HsCodeSearchResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/onboarding\/concierge": { "get": { "operationId": "v1.onboarding.concierge.show", "description": "Returns whether the current store has a pending or handled concierge onboarding request.", "summary": "Get concierge onboarding status", "tags": [ "OnboardingConcierge" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/OnboardingConciergeResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } }, "post": { "operationId": "v1.onboarding.concierge.store", "description": "Creates or returns the store concierge request using the supplied carrier choices and contact details.", "summary": "Request concierge onboarding", "tags": [ "OnboardingConcierge" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "wizard", "settings" ] }, "contact_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "contact_phone": { "type": [ "string", "null" ], "maxLength": 64 }, "message": { "type": [ "string", "null" ], "maxLength": 2000 }, "selected_carriers": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 64 } } }, "required": [ "source" ] } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/OnboardingConciergeResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "403": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/MessageResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/pickup-points": { "get": { "operationId": "v1.pickup-points.index", "description": "Finds real carrier offices and lockers near an address or coordinates and returns typed locations only when available.", "summary": "Search pickup points", "tags": [ "PickupPoints" ], "parameters": [ { "name": "city", "in": "query", "schema": { "type": "string" } }, { "name": "radius_km", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "carrier", "in": "query", "schema": { "type": "string" } }, { "name": "carrier_point_id", "in": "query", "schema": { "type": "string" } }, { "name": "query", "in": "query", "schema": { "type": "string" } }, { "name": "country_code", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "string", "default": 50 } } ], "responses": { "200": { "description": "`PickupPointSearchResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/PickupPointSearchResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/pickup-points\/providers": { "get": { "operationId": "v1.pickup-points.providers", "description": "Summarizes the carriers and pickup-point types currently available in the synchronized catalog.", "summary": "List pickup point providers", "tags": [ "PickupPoints" ], "parameters": [ { "name": "country_code", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PickupPointProvidersResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/PickupPointProvidersResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/pickup-points\/{pickupPoint}": { "get": { "operationId": "v1.pickup-points.show", "description": "Returns one office or locker by its ShipBG pickup-point identifier.", "summary": "Get a pickup point", "tags": [ "PickupPoints" ], "parameters": [ { "name": "pickupPoint", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/PickupPointResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/pickups": { "post": { "operationId": "v1.pickups.store", "description": "Requests collection of labelled shipments from a carrier-supported sender address.", "summary": "Schedule a carrier pickup", "tags": [ "Pickups" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "carrier": { "type": "string" }, "carrier_account_id": { "type": "string", "format": "uuid" }, "pickup_date": { "type": "string", "format": "date" }, "address": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "note": { "type": [ "string", "null" ], "maxLength": 500 }, "shipment_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, "time_window": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] }, "contact": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "name", "phone" ] } }, "required": [ "carrier", "carrier_account_id", "pickup_date", "address", "shipment_ids", "time_window", "contact" ] } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/PickupResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/pickups\/{pickup}": { "get": { "operationId": "v1.pickups.show", "description": "Returns the schedule, shipment IDs, address, contact, and current state of one pickup request.", "summary": "Get a carrier pickup", "tags": [ "Pickups" ], "parameters": [ { "name": "pickup", "in": "path", "required": true, "description": "The pickup ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/PickupResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/plans": { "get": { "operationId": "v1.plans", "description": "Returns visible subscription plans, prices in minor units, shipment limits, and included features.", "summary": "List public plans", "tags": [ "Plans" ], "responses": { "200": { "description": "`PlansResponseResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/PlansResponseResource" } } } }, "429": { "$ref": "#\/components\/responses\/ThrottleRequestsException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/pricing-rule-templates": { "get": { "operationId": "v1.pricing-rule-templates.index", "description": "Returns localized templates that can be copied into merchant pricing rules.", "summary": "List pricing rule templates", "tags": [ "PricingRuleTemplates" ], "responses": { "200": { "description": "`PricingRuleTemplateListResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/PricingRuleTemplateListResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/pricing-rules": { "get": { "operationId": "v1.pricing-rules.index", "description": "Lists ordered checkout pricing conditions and actions for the current integration scope.", "summary": "List pricing rules", "tags": [ "PricingRules" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/PricingRuleResource" } } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } }, "post": { "operationId": "v1.pricing-rules.store", "description": "Creates a checkout pricing rule with typed conditions and actions.", "summary": "Create a pricing rule", "tags": [ "PricingRules" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "enabled": { "type": "boolean" }, "priority": { "type": "integer", "minimum": 0, "maximum": 65535 }, "stop_on_match": { "type": "boolean" }, "domain_id": { "type": [ "string", "null" ], "format": "uuid" }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "order_total", "order_weight", "product_category", "product_shipping_class", "carrier", "delivery_type" ] }, "operator": { "type": "string", "enum": [ "=", "!=", ">", ">=", "<", "<=", "in", "not_in", "contains" ] }, "value": { "type": "string" } }, "required": [ "field", "operator", "value" ] } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "free_shipping", "flat_rate", "percentage_discount", "fixed_discount", "merchant_subsidy" ] }, "value": { "type": [ "integer", "null" ], "minimum": 0 }, "unit": { "type": [ "string", "null" ], "enum": [ "fixed", "percent" ] } }, "required": [ "type" ] }, "minItems": 1, "maxItems": 1 } }, "required": [ "name", "conditions", "actions" ] } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/PricingRuleResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/pricing-rules:reorder": { "post": { "operationId": "v1.pricing-rules.reorder", "description": "Updates evaluation priority for multiple pricing rules and returns the resulting order.", "summary": "Reorder pricing rules", "tags": [ "PricingRules" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/PricingRuleResource" } } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/pricing-rules\/{pricingRule}": { "get": { "operationId": "v1.pricing-rules.show", "description": "Returns one pricing rule with all conditions and actions.", "summary": "Get a pricing rule", "tags": [ "PricingRules" ], "parameters": [ { "name": "pricingRule", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/PricingRuleResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } }, "put": { "operationId": "v1.pricing-rules.update", "description": "Updates one pricing rule and returns the saved conditions, actions, and priority.", "summary": "Update a pricing rule", "tags": [ "PricingRules" ], "parameters": [ { "name": "pricingRule", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "enabled": { "type": "boolean" }, "priority": { "type": "integer", "minimum": 0, "maximum": 65535 }, "stop_on_match": { "type": "boolean" }, "domain_id": { "type": [ "string", "null" ], "format": "uuid" }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "order_total", "order_weight", "product_category", "product_shipping_class", "carrier", "delivery_type" ] }, "operator": { "type": "string", "enum": [ "=", "!=", ">", ">=", "<", "<=", "in", "not_in", "contains" ] }, "value": { "type": "string" } }, "required": [ "field", "operator", "value" ] } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "free_shipping", "flat_rate", "percentage_discount", "fixed_discount", "merchant_subsidy" ] }, "value": { "type": [ "integer", "null" ], "minimum": 0 }, "unit": { "type": [ "string", "null" ], "enum": [ "fixed", "percent" ] } }, "required": [ "type" ] }, "minItems": 1, "maxItems": 1 } }, "required": [ "name", "conditions", "actions" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/PricingRuleResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } }, "delete": { "operationId": "v1.pricing-rules.destroy", "description": "Deletes one pricing rule and returns no response body.", "summary": "Delete a pricing rule", "tags": [ "PricingRules" ], "parameters": [ { "name": "pricingRule", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content", "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/rates:quote": { "post": { "operationId": "v1.rates.quote", "description": "Returns real carrier rate options, normalized money, applied pricing rules, and per-carrier failures for a shipment draft.", "summary": "Quote carrier rates", "tags": [ "Rates" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/QuoteRatesCommand" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/RateQuoteResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/shipments\/{shipment}\/returns": { "post": { "operationId": "v1.shipments.returns.store", "description": "Creates a carrier return for the source shipment and returns the resulting return-shipment record.", "summary": "Create a return shipment", "tags": [ "Returns" ], "parameters": [ { "name": "shipment", "in": "path", "required": true, "description": "The shipment ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 }, "notes": { "type": [ "string", "null" ], "maxLength": 1000 }, "pickup_type": { "type": [ "string", "null" ], "enum": [ "address", "office", "locker" ] }, "from_address": { "type": [ "array", "null" ], "items": { "type": "string" } }, "to_address": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "reason" ] } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ReturnShipmentResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } }, "get": { "operationId": "v1.shipments.returns.index", "description": "Lists return shipments associated with one source shipment.", "summary": "List returns for a shipment", "tags": [ "Returns" ], "parameters": [ { "name": "shipment", "in": "path", "required": true, "description": "The shipment ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "carrier", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`ReturnShipmentListResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ReturnShipmentListResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/returns": { "get": { "operationId": "v1.returns.index", "description": "Lists return shipments for the current integration scope.", "summary": "List return shipments", "tags": [ "Returns" ], "parameters": [ { "name": "original_shipment_id", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "carrier", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`ReturnShipmentListResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ReturnShipmentListResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/returns\/{returnShipment}": { "get": { "operationId": "v1.returns.show", "description": "Returns one return shipment, its carrier state, tracking code, and label availability.", "summary": "Get a return shipment", "tags": [ "Returns" ], "parameters": [ { "name": "returnShipment", "in": "path", "required": true, "description": "The return shipment ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ReturnShipmentResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/returns\/{returnShipment}\/label": { "get": { "operationId": "v1.returns.label", "description": "Downloads the return shipment label as a PDF document.", "summary": "Download a return label", "tags": [ "Returns" ], "parameters": [ { "name": "returnShipment", "in": "path", "required": true, "description": "The return shipment ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application\/pdf": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Content-Disposition": { "schema": { "type": "string" } }, "Content-Length": { "schema": { "type": "string" } }, "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/shipments": { "get": { "operationId": "v1.shipments.index", "description": "Lists shipments with cursor pagination and optional rate or tracking expansions.", "summary": "List shipments", "tags": [ "Shipments" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "carrier", "in": "query", "schema": { "type": "string" } }, { "name": "tracking_code", "in": "query", "schema": { "type": "string" } }, { "name": "order_ref", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`ShipmentListResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ShipmentListResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } }, "post": { "operationId": "v1.shipments.store", "description": "Creates a shipment from typed sender, recipient, parcel, and carrier options; use an idempotency key for safe retries.", "summary": "Create a shipment", "tags": [ "Shipments" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateShipmentCommand" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ShipmentResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/shipments\/{shipment}": { "get": { "operationId": "v1.shipments.show", "description": "Returns one shipment with optional stored-rate and tracking-event expansions.", "summary": "Get a shipment", "tags": [ "Shipments" ], "parameters": [ { "name": "shipment", "in": "path", "required": true, "description": "The shipment ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ShipmentResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } }, "patch": { "operationId": "v1.shipments.update", "description": "Updates a mutable shipment and returns a conflict when its lifecycle state no longer allows changes.", "summary": "Update a shipment", "tags": [ "Shipments" ], "parameters": [ { "name": "shipment", "in": "path", "required": true, "description": "The shipment ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ShipmentResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "409": { "$ref": "#\/components\/responses\/ConflictException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/shipments\/{shipment}:generate-label": { "post": { "operationId": "v1.shipments.generate-label", "description": "Purchases or generates the carrier label and returns the updated labelled shipment.", "summary": "Generate a shipment label", "tags": [ "Shipments" ], "parameters": [ { "name": "shipment", "in": "path", "required": true, "description": "The shipment ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "paper_size": { "type": [ "string", "null" ], "description": "Values are carrier-specific (Speedy A4\/A6\/A4_4xA6, Pigeon default\/a4,\nBoxNow pdf\/zpl), so the adapter validates \u2014 a hardcoded pair here\nrejected A4_4xA6, which Speedy's own schema accepts.", "maxLength": 32 } } } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ShipmentResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/shipments\/{shipment}\/label": { "get": { "operationId": "v1.shipments.label", "description": "Downloads the generated carrier label as a PDF document.", "summary": "Download a shipment label", "tags": [ "Shipments" ], "parameters": [ { "name": "shipment", "in": "path", "required": true, "description": "The shipment ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application\/pdf": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Content-Disposition": { "schema": { "type": "string" } }, "Content-Length": { "schema": { "type": "string" } }, "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/shipments\/{shipment}:cancel": { "post": { "operationId": "v1.shipments.cancel", "description": "Cancels the shipment with its carrier and returns a conflict when cancellation is no longer allowed.", "summary": "Cancel a shipment", "tags": [ "Shipments" ], "parameters": [ { "name": "shipment", "in": "path", "required": true, "description": "The shipment ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ShipmentResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "409": { "$ref": "#\/components\/responses\/ConflictException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/shipments\/{shipment}\/tracking-events": { "get": { "operationId": "v1.shipments.tracking-events", "description": "Returns the normalized tracking timeline with cursor metadata for one shipment.", "summary": "List tracking events", "tags": [ "Shipments" ], "parameters": [ { "name": "shipment", "in": "path", "required": true, "description": "The shipment ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`TrackingTimelineResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TrackingTimelineResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/shipments\/{shipment}\/tracking:refresh": { "post": { "operationId": "v1.shipments.tracking-refresh", "description": "Fetches the latest carrier tracking state and returns the refreshed normalized timeline.", "summary": "Refresh shipment tracking", "tags": [ "Shipments" ], "parameters": [ { "name": "shipment", "in": "path", "required": true, "description": "The shipment ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`TrackingTimelineResource`", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TrackingTimelineResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/webhook-subscriptions": { "get": { "operationId": "v1.webhook-subscriptions.index", "description": "Lists signing-enabled webhook endpoints without returning their secrets. Delivery and failure transitions currently arrive through shipment.status_changed.", "summary": "List webhook subscriptions", "tags": [ "WebhookSubscriptions" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/WebhookSubscriptionResource" } } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } }, "post": { "operationId": "v1.webhook-subscriptions.store", "description": "Creates a signed HTTPS webhook subscription and returns its HMAC secret once. Distinct shipment.delivered and shipment.failed events are accepted but are not currently emitted.", "summary": "Create a webhook subscription", "tags": [ "WebhookSubscriptions" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "url", "events" ] } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookSubscriptionCreatedResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/webhook-subscriptions\/{webhookSubscription}": { "get": { "operationId": "v1.webhook-subscriptions.show", "description": "Returns one webhook endpoint, event filters, and secret-presence flag without the signing secret.", "summary": "Get a webhook subscription", "tags": [ "WebhookSubscriptions" ], "parameters": [ { "name": "webhookSubscription", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookSubscriptionResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } }, "delete": { "operationId": "v1.webhook-subscriptions.destroy", "description": "Deletes one webhook endpoint and returns no response body.", "summary": "Delete a webhook subscription", "tags": [ "WebhookSubscriptions" ], "parameters": [ { "name": "webhookSubscription", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content", "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/webhook-subscriptions\/{webhookSubscription}\/test": { "post": { "operationId": "v1.webhook-subscriptions.test", "description": "Sends a signed test event to the endpoint and reports the delivery result.", "summary": "Test a webhook subscription", "tags": [ "WebhookSubscriptions" ], "parameters": [ { "name": "webhookSubscription", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookTestResultResource" } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } }, "\/webhook-subscriptions\/{webhookSubscription}\/attempts": { "get": { "operationId": "v1.webhook-subscriptions.attempts", "description": "Returns recent signed payload envelopes, attempt state, response status, and retry timing for one subscription.", "summary": "List webhook delivery attempts", "tags": [ "WebhookSubscriptions" ], "parameters": [ { "name": "webhookSubscription", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/WebhookAttemptResource" } } }, "required": [ "data" ] } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "500": { "$ref": "#\/components\/responses\/InternalServerError" } } } } }, "components": { "schemas": { "Account202607Resource": { "type": "object", "properties": { "user": { "$ref": "#\/components\/schemas\/AccountUserResource" }, "domain": { "$ref": "#\/components\/schemas\/AccountDomainResource" }, "subscription": { "anyOf": [ { "$ref": "#\/components\/schemas\/AccountSubscriptionResource" }, { "type": "null" } ] }, "usage": { "$ref": "#\/components\/schemas\/AccountUsageResource" } }, "required": [ "user", "domain", "subscription", "usage" ], "title": "Account202607Resource" }, "Account20260806Resource": { "type": "object", "properties": { "user": { "$ref": "#\/components\/schemas\/AccountUserResource" }, "domain": { "$ref": "#\/components\/schemas\/AccountDomainResource" }, "subscription": { "anyOf": [ { "$ref": "#\/components\/schemas\/AccountSubscriptionResource" }, { "type": "null" } ] }, "usage": { "$ref": "#\/components\/schemas\/AccountUsageResource" }, "integration": { "$ref": "#\/components\/schemas\/AccountIntegrationResource" } }, "required": [ "user", "domain", "subscription", "usage", "integration" ], "title": "Account20260806Resource" }, "AccountDomainResource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Effective merchant domain UUID." }, "name": { "type": "string", "description": "Merchant domain name." }, "tier": { "type": "string", "enum": [ "free", "growth" ] }, "is_active": { "type": "boolean" } }, "required": [ "id", "name", "tier", "is_active" ], "title": "AccountDomainResource" }, "AccountIntegrationFeaturesResource": { "type": "object", "properties": { "backend_rollout_audit": { "type": "string", "enum": [ "disabled", "enabled", "hotfix" ] }, "editable_cod_amount": { "type": "string", "enum": [ "disabled", "enabled", "hotfix" ] }, "integration_pilot_badge": { "type": "string", "enum": [ "disabled", "enabled", "hotfix" ] } }, "required": [ "backend_rollout_audit", "integration_pilot_badge" ], "title": "AccountIntegrationFeaturesResource" }, "AccountIntegrationResource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Resolved API integration UUID." }, "api_contract": { "type": "string", "description": "Backend-assigned active API contract for this integration.", "const": "2026-08-06" }, "features": { "$ref": "#\/components\/schemas\/AccountIntegrationFeaturesResource" } }, "required": [ "id", "api_contract", "features" ], "title": "AccountIntegrationResource" }, "AccountProfileResource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "title": "AccountProfileResource" }, "AccountSubscriptionResource": { "type": "object", "properties": { "status": { "type": [ "string", "null" ] }, "tier": { "type": [ "string", "null" ] }, "current_period_end": { "type": [ "string", "null" ], "format": "date-time", "description": "Current billing period end, when available." }, "manage_url": { "type": [ "string", "null" ], "format": "uri", "description": "Customer billing-management URL, when available." } }, "required": [ "status", "tier", "current_period_end", "manage_url" ], "title": "AccountSubscriptionResource" }, "AccountUsageResource": { "type": "object", "properties": { "monthly_api_requests": { "type": "integer", "description": "API requests recorded for the effective domain in the current month." }, "monthly_shipments": { "type": "integer", "description": "Shipments created for the effective domain in the current month." }, "shipment_limit": { "type": "integer", "description": "Monthly shipment allowance for the effective domain tier." }, "paid_domains_count": { "type": "integer" }, "free_domains_count": { "type": "integer" } }, "required": [ "monthly_api_requests", "monthly_shipments", "shipment_limit", "paid_domains_count", "free_domains_count" ], "title": "AccountUsageResource" }, "AccountUserResource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Authenticated user UUID." }, "email": { "type": "string", "format": "email", "description": "Authenticated user email address." }, "name": { "type": [ "string", "null" ], "description": "Display name; null when the user has not set one." } }, "required": [ "id", "email", "name" ], "title": "AccountUserResource" }, "AddressData": { "type": "object", "properties": { "name": { "type": "string" }, "company": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "country_code": { "type": "string" }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "street": { "type": "string" }, "street_number": { "type": "string" }, "address_line": { "type": "string" } }, "title": "AddressData" }, "ApiTokenResource": { "type": "object", "properties": { "access_token": { "type": "string", "description": "Bearer token shown only in this issuance response. Store it securely; ShipBG cannot return it again." }, "token_id": { "type": "string", "description": "Token identifier used by the revoke endpoint." }, "device_name": { "type": "string" }, "domain_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "access_token", "token_id", "device_name", "domain_id" ], "title": "ApiTokenResource" }, "AppliedPricingRuleResource": { "type": "object", "properties": { "rule_id": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "action_type": { "type": "string" }, "action_value": { "description": "Rule action value; its JSON type depends on the action type." } }, "required": [ "rule_id", "type", "label", "action_type", "action_value" ], "title": "AppliedPricingRuleResource" }, "AutocompleteAddressResource": { "type": "object", "properties": { "suggestions": { "type": "array", "description": "Ranked address suggestions.", "items": { "$ref": "#\/components\/schemas\/AutocompleteAddressSuggestionResource" } } }, "required": [ "suggestions" ], "title": "AutocompleteAddressResource" }, "AutocompleteAddressSuggestionResource": { "type": "object", "properties": { "latitude": { "type": "number", "description": "WGS84 latitude in decimal degrees.", "example": 42.6977 }, "longitude": { "type": "number", "description": "WGS84 longitude in decimal degrees.", "example": 23.3219 }, "address": { "type": [ "string", "null" ], "description": "Provider-formatted address when available." }, "provider": { "type": "string", "description": "Geocoding provider that supplied the suggestion.", "example": "photon" }, "confidence": { "type": [ "number", "null" ], "description": "Provider confidence from 0 to 1 when available.", "example": 0.7 } }, "required": [ "latitude", "longitude", "address", "provider", "confidence" ], "title": "AutocompleteAddressSuggestionResource" }, "BuildCheckoutOptionsCommand": { "type": "object", "properties": { "sender": { "$ref": "#\/components\/schemas\/AddressData" }, "recipient": { "$ref": "#\/components\/schemas\/AddressData" }, "parcel": { "$ref": "#\/components\/schemas\/ParcelData" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "carriers": { "type": "array", "items": { "type": "string" } }, "options": { "anyOf": [ { "$ref": "#\/components\/schemas\/ShipmentOptionsData" }, { "type": "null" } ] }, "carrier_options": { "anyOf": [ { "$ref": "#\/components\/schemas\/CarrierOptionsData" }, { "type": "null" } ] }, "radius_km": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "limit_pickup": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200 }, "recipient_latitude": { "type": [ "number", "null" ], "minimum": -90, "maximum": 90 }, "recipient_longitude": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180 }, "geocode_recipient": { "type": "boolean" }, "order_total": { "type": [ "integer", "null" ], "minimum": 0 }, "product_categories": { "type": [ "array", "null" ], "items": { "type": "string" } }, "product_shipping_classes": { "type": [ "array", "null" ], "items": { "type": "string" } }, "user_id": { "type": [ "string", "null" ], "format": "uuid" }, "domain_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "sender", "recipient", "parcel" ], "title": "BuildCheckoutOptionsCommand" }, "BulkBatchResource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Bulk batch UUID." }, "type": { "type": "string", "description": "Bulk operation type.", "enum": [ "bulk_generate_labels", "bulk_cancel" ] }, "status": { "type": "string", "description": "Asynchronous batch status.", "enum": [ "pending", "running", "completed", "failed" ] }, "total": { "type": "integer", "description": "Total shipments queued.", "example": 20 }, "succeeded": { "type": "integer", "description": "Shipments processed successfully.", "example": 18 }, "failed": { "type": "integer", "description": "Shipments that failed processing.", "example": 2 }, "progress": { "type": "integer", "description": "Integer completion percentage from 0 to 100.", "example": 100 }, "shipment_ids": { "type": "array", "description": "Shipment UUIDs queued in this batch.", "items": { "type": "string", "format": "uuid" } }, "results": { "type": "array", "description": "Per-shipment outcomes; empty until processing starts.", "items": { "$ref": "#\/components\/schemas\/BulkBatchResultResource" } }, "merged_label_url": { "type": [ "string", "null" ], "description": "URL of the merged PDF after successful bulk label generation." }, "started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Batch processing start time." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Batch processing completion time." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Batch creation time." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Batch last-update time." } }, "required": [ "id", "type", "status", "total", "succeeded", "failed", "progress", "shipment_ids", "results", "merged_label_url", "started_at", "completed_at", "created_at", "updated_at" ], "title": "BulkBatchResource" }, "BulkBatchResultResource": { "type": "object", "properties": { "shipment_id": { "type": "string", "format": "uuid", "description": "Shipment UUID processed by the batch." }, "status": { "type": "string", "description": "Per-shipment processing outcome.", "enum": [ "success", "failed" ] }, "tracking_code": { "type": [ "string", "null" ], "description": "Carrier tracking code after successful label generation." }, "error_code": { "type": "string", "description": "Stable failure code when processing failed." }, "error_message": { "type": "string", "description": "Failure explanation when processing failed." } }, "required": [ "shipment_id", "status" ], "title": "BulkBatchResultResource" }, "CarrierAccountDefaultsResource": { "type": "object", "properties": { "data": { "description": "Defaults keyed by carrier slug. Each value contains the stable fields shown here and may also include carrier-specific per-shipment defaults configured by the merchant. Credential fields are never returned.", "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "properties": { "carrier": { "$ref": "#\/components\/schemas\/CarrierSlug" }, "sender": { "type": "object", "additionalProperties": {} }, "sender_config": { "type": "object", "additionalProperties": {} }, "service_code": { "type": [ "string", "null" ] }, "is_test": { "type": "boolean" } }, "required": [ "carrier", "sender", "sender_config", "service_code", "is_test" ] } }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] } }, "required": [ "data" ], "title": "CarrierAccountDefaultsResource" }, "CarrierAccountListResource": { "type": "object", "properties": { "data": { "type": "array", "description": "Merchant courier accounts.", "items": { "$ref": "#\/components\/schemas\/CarrierAccountResource" } } }, "required": [ "data" ], "title": "CarrierAccountListResource" }, "CarrierAccountResource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Courier account UUID." }, "carrier": { "type": "string", "description": "Stable carrier slug.", "enum": [ "speedy", "econt", "boxnow", "postone", "direx", "sameday", "bgpost", "a1post", "pigeon" ] }, "name": { "type": [ "string", "null" ], "description": "Merchant-defined account display name." }, "is_active": { "type": "boolean", "description": "Whether this account may be used for live ShipBG operations." }, "is_test": { "type": "boolean", "description": "Whether this account targets the carrier sandbox environment." }, "has_credentials": { "type": "boolean", "description": "Whether encrypted carrier credentials are configured; credential values are never returned." }, "sender_config": { "description": "Sender configuration plus only catalog-declared public onboarding identifiers; secret credential fields are never emitted.", "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "settings": { "description": "Carrier-specific non-secret settings defined by the carrier catalog; this field never contains credentials.", "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Account creation time." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Account last-update time." } }, "required": [ "id", "carrier", "name", "is_active", "is_test", "has_credentials", "sender_config", "settings", "created_at", "updated_at" ], "title": "CarrierAccountResource" }, "CarrierCapabilitiesResource": { "type": "object", "properties": { "carrier": { "type": "string", "description": "Stable carrier slug.", "enum": [ "speedy", "econt", "boxnow", "postone", "direx", "sameday", "bgpost", "a1post", "pigeon" ] }, "contracts": { "type": "array", "description": "Live carrier-specific contract records; object fields vary by carrier.", "items": { "type": "object", "additionalProperties": {} } }, "services": { "type": "array", "description": "Live carrier-specific service records; object fields vary by carrier.", "items": { "type": "object", "additionalProperties": {} } }, "agreements": { "type": "array", "description": "Live carrier-specific COD agreement records; object fields vary by carrier.", "items": { "type": "object", "additionalProperties": {} } }, "lockers": { "type": "array", "description": "Live carrier-specific merchant locker records; object fields vary by carrier.", "items": { "type": "object", "additionalProperties": {} } } }, "required": [ "carrier", "contracts", "services", "agreements", "lockers" ], "title": "CarrierCapabilitiesResource" }, "CarrierConnectionTestResource": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CarrierConnectionTestResultResource" } }, "required": [ "data" ], "title": "CarrierConnectionTestResource" }, "CarrierConnectionTestResultResource": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the carrier accepted the supplied or stored credentials." }, "carrier": { "type": [ "string", "null" ], "description": "Carrier that was tested; null when a stored account could not be resolved.", "enum": [ "speedy", "econt", "boxnow", "postone", "direx", "sameday", "bgpost", "a1post", "pigeon" ] }, "message": { "type": [ "string", "null" ], "description": "Carrier or validation error explanation; null after a successful test." } }, "required": [ "success", "carrier", "message" ], "title": "CarrierConnectionTestResultResource" }, "CarrierDiscoveryResource": { "type": "object", "properties": { "data": { "description": "Live, carrier-defined discovery collections keyed by category (for example products, senders, or insurances). Item fields depend on the carrier and category and contain no account credentials.", "anyOf": [ { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] } }, "required": [ "data" ], "title": "CarrierDiscoveryResource" }, "CarrierFieldDescriptorResource": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "surfaces": { "type": "array", "description": "Plugin surfaces where the field is rendered.", "items": { "type": "string" } }, "wire_key": { "type": "string" }, "defaultable": { "type": "boolean" }, "applies_when": { "type": "object", "description": "Field-value conditions that control whether this descriptor applies." }, "options": { "type": [ "array", "null" ], "description": "Static select values; labels are translated client-side.", "items": { "type": "string" } }, "default": { "description": "Default field value; its JSON type depends on the field type." }, "empty_option": { "type": "boolean" }, "empty_label_key": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "desc_tip": { "type": "boolean" }, "input_type": { "type": [ "string", "null" ] }, "css_class": { "type": [ "string", "null" ] }, "options_source": { "type": "string" }, "render": { "type": [ "string", "null" ] } }, "required": [ "key", "type", "surfaces", "wire_key", "defaultable", "applies_when", "options", "default", "empty_option", "empty_label_key", "description", "desc_tip", "input_type", "css_class", "options_source", "render" ], "title": "CarrierFieldDescriptorResource" }, "CarrierLabelFormatResource": { "type": "object", "properties": { "setting_key": { "type": "string" }, "values": { "type": "object", "description": "Carrier-supported label render choices." } }, "required": [ "setting_key", "values" ], "title": "CarrierLabelFormatResource" }, "CarrierManifestEntryResource": { "type": "object", "properties": { "slug": { "type": "string", "description": "Stable carrier slug.", "example": "speedy" }, "name": { "type": "string", "description": "Human-readable carrier name.", "example": "Speedy" }, "capabilities": { "type": "array", "description": "Account-independent carrier capability identifiers.", "items": { "type": "string" } }, "supports_sandbox": { "type": "boolean" }, "supports_international": { "type": "boolean" }, "option_fields": { "type": "array", "description": "Per-shipment option field descriptors.", "items": { "$ref": "#\/components\/schemas\/CarrierFieldDescriptorResource" } }, "setting_fields": { "type": "array", "description": "Merchant setting field descriptors.", "items": { "$ref": "#\/components\/schemas\/CarrierFieldDescriptorResource" } }, "label_format": { "anyOf": [ { "$ref": "#\/components\/schemas\/CarrierLabelFormatResource" }, { "type": "null" } ] } }, "required": [ "slug", "name", "capabilities", "supports_sandbox", "supports_international", "option_fields", "setting_fields", "label_format" ], "title": "CarrierManifestEntryResource" }, "CarrierManifestResource": { "type": "object", "properties": { "data": { "type": "array", "description": "Registered carrier integrations and their platform-facing capabilities.", "items": { "$ref": "#\/components\/schemas\/CarrierManifestEntryResource" } } }, "required": [ "data" ], "title": "CarrierManifestResource" }, "CarrierOptionsData": { "type": "object", "properties": { "speedy": { "type": "array", "items": { "type": "string" } }, "econt": { "type": "array", "items": { "type": "string" } }, "boxnow": { "type": "array", "items": { "type": "string" } }, "postone": { "type": "array", "items": { "type": "string" } }, "direx": { "type": "array", "items": { "type": "string" } }, "sameday": { "type": "array", "items": { "type": "string" } }, "bgpost": { "type": "array", "items": { "type": "string" } }, "a1post": { "type": "array", "items": { "type": "string" } }, "pigeon": { "type": "array", "items": { "type": "string" } } }, "required": [ "speedy", "econt", "boxnow", "postone", "direx", "sameday", "bgpost", "a1post", "pigeon" ], "title": "CarrierOptionsData" }, "CarrierRoutingEntry": { "type": "object", "properties": { "delivery_type": { "type": "string" }, "carrier": { "type": "string" }, "priority": { "type": "integer" }, "enabled": { "type": "boolean" } }, "required": [ "delivery_type", "carrier", "priority", "enabled" ], "title": "CarrierRoutingEntry" }, "CarrierRoutingEntryResource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Routing rule UUID." }, "carrier": { "type": "string", "description": "Stable carrier slug.", "enum": [ "speedy", "econt", "boxnow", "postone", "direx", "sameday", "bgpost", "a1post", "pigeon" ] }, "priority": { "type": "integer", "description": "Lower values are evaluated first.", "example": 0 }, "enabled": { "type": "boolean", "description": "Whether this routing entry is enabled." }, "active_account": { "type": "boolean", "description": "Whether the merchant currently has an active account for this carrier." } }, "required": [ "id", "carrier", "priority", "enabled", "active_account" ], "title": "CarrierRoutingEntryResource" }, "CarrierRoutingMatrixResource": { "type": "object", "properties": { "address": { "type": "array", "description": "Address-delivery routing order.", "items": { "$ref": "#\/components\/schemas\/CarrierRoutingEntryResource" } }, "office": { "type": "array", "description": "Office-delivery routing order.", "items": { "$ref": "#\/components\/schemas\/CarrierRoutingEntryResource" } }, "locker": { "type": "array", "description": "Locker-delivery routing order.", "items": { "$ref": "#\/components\/schemas\/CarrierRoutingEntryResource" } } }, "required": [ "address", "office", "locker" ], "title": "CarrierRoutingMatrixResource" }, "CarrierRoutingResource": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CarrierRoutingMatrixResource" }, "warnings": { "type": "array", "description": "Configuration warnings that do not prevent saving the routing matrix.", "items": { "type": "string" } } }, "required": [ "data", "warnings" ], "title": "CarrierRoutingResource" }, "CarrierSlug": { "type": "string", "enum": [ "speedy", "econt", "boxnow", "postone", "direx", "sameday", "bgpost", "a1post", "pigeon" ], "title": "CarrierSlug" }, "CarrierVerificationDestinationsResource": { "type": "object", "properties": { "data": { "type": "array", "description": "Sample destinations supported by the requested carriers.", "items": { "$ref": "#\/components\/schemas\/CarrierVerificationScenarioResource" } } }, "required": [ "data" ], "title": "CarrierVerificationDestinationsResource" }, "CarrierVerificationRecipientResource": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "city": { "type": "string" }, "postal_code": { "type": "string" }, "country_code": { "type": "string" }, "street": { "type": "string" }, "street_number": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "required": [ "name", "phone", "city", "postal_code", "country_code", "street", "street_number", "latitude", "longitude" ], "title": "CarrierVerificationRecipientResource" }, "CarrierVerificationScenarioResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "recipient": { "$ref": "#\/components\/schemas\/CarrierVerificationRecipientResource" }, "carriers": { "type": "array", "description": "Carrier slugs supporting this sample destination.", "items": { "type": "string" } }, "delivery_types_by_carrier": { "type": "object", "description": "Canonical delivery types keyed by carrier slug.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "id", "name", "recipient", "carriers", "delivery_types_by_carrier" ], "title": "CarrierVerificationScenarioResource" }, "CheckoutDeliveryOptionResource": { "type": "object", "properties": { "id": { "type": "string" }, "carrier": { "type": "string" }, "delivery_type": { "type": "string" }, "delivery_group": { "type": "string" }, "service_type": { "type": "string" }, "location_name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "coordinates": { "anyOf": [ { "$ref": "#\/components\/schemas\/CoordinatesResource" }, { "type": "null" } ] }, "price": { "$ref": "#\/components\/schemas\/MoneyResource" }, "distance_meters": { "type": [ "integer", "null" ] }, "estimated_days": { "type": [ "integer", "null" ] }, "supports_cod": { "type": "boolean" }, "service_code": { "type": "string" }, "service_name": { "type": "string" }, "checkout_label": { "type": [ "string", "null" ] }, "carrier_account_id": { "type": [ "string", "null" ] }, "pickup_point_id": { "type": [ "string", "null" ] }, "tag": { "type": [ "string", "null" ] }, "metadata": { "description": "Carrier-specific metadata whose JSON shape is intentionally not guaranteed." }, "applied_rules": { "type": "array", "items": { "$ref": "#\/components\/schemas\/AppliedPricingRuleResource" } }, "rate_source": { "type": "string" } }, "required": [ "id", "carrier", "delivery_type", "delivery_group", "service_type", "location_name", "address", "coordinates", "price", "distance_meters", "estimated_days", "supports_cod", "service_code", "service_name", "checkout_label", "carrier_account_id", "pickup_point_id", "tag", "metadata", "applied_rules", "rate_source" ], "title": "CheckoutDeliveryOptionResource" }, "CheckoutOptionsResource": { "type": "object", "properties": { "currency": { "type": "string" }, "home_min": { "anyOf": [ { "$ref": "#\/components\/schemas\/MoneyResource" }, { "type": "null" } ] }, "pickup_min": { "anyOf": [ { "$ref": "#\/components\/schemas\/MoneyResource" }, { "type": "null" } ] }, "customer_coordinates": { "anyOf": [ { "$ref": "#\/components\/schemas\/CoordinatesResource" }, { "type": "null" } ] }, "carrier_icons": { "type": "object", "additionalProperties": { "type": "string" } }, "home_options": { "type": "array", "items": { "$ref": "#\/components\/schemas\/CheckoutDeliveryOptionResource" } }, "pickup_options": { "type": "array", "items": { "$ref": "#\/components\/schemas\/CheckoutDeliveryOptionResource" } }, "errors": { "type": "array", "items": { "$ref": "#\/components\/schemas\/RateErrorResource" } } }, "required": [ "currency", "home_min", "pickup_min", "customer_coordinates", "carrier_icons", "home_options", "pickup_options", "errors" ], "title": "CheckoutOptionsResource" }, "CodPaymentData": { "type": "object", "properties": { "order_total": { "type": "integer" }, "shipping_total": { "type": "integer" }, "paid_amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "order_total", "shipping_total", "paid_amount", "currency" ], "title": "CodPaymentData" }, "CoordinatesResource": { "type": "object", "properties": { "latitude": { "type": "number", "description": "WGS84 latitude in decimal degrees.", "example": 42.6977 }, "longitude": { "type": "number", "description": "WGS84 longitude in decimal degrees.", "example": 23.3219 } }, "required": [ "latitude", "longitude" ], "title": "CoordinatesResource" }, "CreateCarrierAccountCommand": { "type": "object", "properties": { "carrier": { "type": "string", "enum": [ "speedy", "econt", "boxnow", "postone", "direx", "sameday", "bgpost", "a1post", "pigeon" ] }, "credentials": { "type": "array", "items": { "type": "string" } }, "settings": { "type": [ "array", "null" ], "items": { "type": "string" } }, "is_active": { "type": [ "boolean", "null" ] }, "is_test": { "type": [ "boolean", "null" ] }, "user_id": { "type": [ "string", "null" ], "format": "uuid" }, "domain_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "carrier", "credentials" ], "title": "CreateCarrierAccountCommand" }, "CreateShipmentCommand": { "type": "object", "properties": { "carrier": { "type": "string" }, "to_address": { "$ref": "#\/components\/schemas\/AddressData" }, "parcel": { "$ref": "#\/components\/schemas\/ParcelData" }, "from_address": { "anyOf": [ { "$ref": "#\/components\/schemas\/AddressData" }, { "type": "null" } ] }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "goods": { "type": [ "array", "null" ], "items": { "$ref": "#\/components\/schemas\/GoodsItemData" } }, "carrier_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "service_code": { "type": [ "string", "null" ], "maxLength": 50 }, "options": { "anyOf": [ { "$ref": "#\/components\/schemas\/ShipmentOptionsData" }, { "type": "null" } ] }, "cod": { "anyOf": [ { "$ref": "#\/components\/schemas\/CodPaymentData" }, { "type": "null" } ] }, "carrier_options": { "type": [ "array", "null" ], "items": { "type": "string" } }, "order_ref": { "type": [ "string", "null" ], "maxLength": 255 }, "user_id": { "type": [ "string", "null" ], "format": "uuid" }, "domain_id": { "type": [ "string", "null" ], "format": "uuid" }, "rate_snapshot": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "carrier", "to_address", "parcel" ], "title": "CreateShipmentCommand" }, "CursorPaginationResource": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or null when this is the final page." }, "has_more": { "type": "boolean", "description": "Whether another page is available." }, "count": { "type": "integer", "description": "Number of records returned in this page.", "example": 25 } }, "required": [ "cursor", "has_more", "count" ], "title": "CursorPaginationResource" }, "EcontAddressValidationResource": { "type": "object", "properties": { "status": { "type": "string", "description": "Econt validation status; `normal` means the address is resolvable.", "example": "normal" }, "parsed": { "$ref": "#\/components\/schemas\/EcontParsedAddressResource" }, "message": { "type": [ "string", "null" ], "description": "Carrier guidance when the address is invalid or incomplete." } }, "required": [ "status", "parsed", "message" ], "title": "EcontAddressValidationResource" }, "EcontNomenclatureItemResource": { "type": "object", "properties": { "id": { "type": "integer", "description": "Econt nomenclature identifier." }, "name": { "type": "string" }, "postCode": { "type": [ "string", "null" ], "description": "City postal code. Street and quarter results omit this field." } }, "required": [ "id", "name" ], "title": "EcontNomenclatureItemResource" }, "EcontNomenclatureResource": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#\/components\/schemas\/EcontNomenclatureItemResource" } } }, "required": [ "items" ], "title": "EcontNomenclatureResource" }, "EcontParsedAddressResource": { "type": "object", "properties": { "street": { "type": [ "string", "null" ], "description": "Street parsed by Econt." }, "num": { "type": [ "string", "null" ], "description": "Street number parsed by Econt." }, "quarter": { "type": [ "string", "null" ], "description": "Quarter parsed by Econt." }, "other": { "type": [ "string", "null" ], "description": "Additional address detail parsed by Econt." } }, "required": [ "street", "num", "quarter", "other" ], "title": "EcontParsedAddressResource" }, "EmailChangeConfirmationResource": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": [ "email" ], "title": "EmailChangeConfirmationResource" }, "EmailChangeRequestResource": { "type": "object", "properties": { "new_email": { "type": "string", "format": "email" }, "expires_at": { "type": "string", "format": "date-time", "description": "Verification-code expiry." } }, "required": [ "new_email", "expires_at" ], "title": "EmailChangeRequestResource" }, "GeocodeAddressCommand": { "type": "object", "properties": { "address": { "type": "string", "minLength": 2, "maxLength": 255 }, "city": { "type": [ "string", "null" ], "maxLength": 100 }, "postal_code": { "type": [ "string", "null" ], "maxLength": 20 }, "country": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 } }, "required": [ "address" ], "title": "GeocodeAddressCommand" }, "GeocodeResource": { "type": "object", "properties": { "latitude": { "type": "number", "description": "WGS84 latitude in decimal degrees.", "example": 42.6977 }, "longitude": { "type": "number", "description": "WGS84 longitude in decimal degrees.", "example": 23.3219 }, "provider": { "type": "string", "description": "Geocoding provider that resolved the address.", "example": "google_maps" }, "confidence": { "type": [ "number", "null" ], "description": "Provider confidence from 0 to 1 when available.", "example": 0.95 }, "cache_hit": { "type": "boolean", "description": "Whether the result came from ShipBG geocoding cache." }, "address": { "type": [ "string", "null" ], "description": "Provider-formatted address when available." } }, "required": [ "latitude", "longitude", "provider", "confidence", "cache_hit", "address" ], "title": "GeocodeResource" }, "GoodsItemData": { "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "integer" }, "unit_value": { "type": "integer" }, "unit_weight": { "type": "number" }, "hs_code": { "type": "string" }, "origin_country_code": { "type": "string" } }, "required": [ "description", "quantity", "unit_value" ], "title": "GoodsItemData" }, "HealthResource": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "version": { "type": "string", "description": "Deployed backend version.", "example": "backend-v1.8.0" }, "timestamp": { "type": "string", "format": "date-time" }, "services": { "type": "object", "description": "Health status keyed by dependency or advisory check name.", "additionalProperties": { "type": "string", "enum": [ "ok", "degraded" ] } } }, "required": [ "status", "version", "timestamp", "services" ], "title": "HealthResource" }, "HealthResponseResource": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/HealthResource" } }, "required": [ "data" ], "title": "HealthResponseResource" }, "HsCodeResource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable UUID for this tariff-code record." }, "hscode": { "type": "string", "description": "Tariff classification code.", "example": "3304.99" }, "description": { "type": "string", "description": "Official tariff-code description." }, "indent": { "type": "integer", "description": "Depth within the tariff-code hierarchy.", "example": 2 }, "is_leaf": { "type": "boolean", "description": "Whether this code can be selected for a customs line item.", "example": true }, "source": { "type": "string", "description": "Catalog source identifier.", "example": "eu_cn_taric" }, "jurisdiction": { "type": [ "string", "null" ], "description": "Two-letter jurisdiction code when the catalog is territory-specific.", "example": "EU" }, "hts_version": { "type": "string", "description": "Published tariff catalog version.", "example": "2026" }, "valid_from": { "type": [ "string", "null" ], "format": "date", "description": "First date on which the code is valid.", "example": "2026-01-01" }, "valid_to": { "type": [ "string", "null" ], "format": "date", "description": "Last date on which the code is valid, or null while current." }, "parent_code": { "type": [ "string", "null" ], "description": "Parent tariff code, or null for a root code.", "example": "3304" } }, "required": [ "id", "hscode", "description", "indent", "is_leaf", "source", "jurisdiction", "hts_version", "valid_from", "valid_to", "parent_code" ], "title": "HsCodeResource" }, "HsCodeSearchResource": { "type": "object", "properties": { "data": { "type": "array", "description": "Tariff codes matching the search criteria.", "items": { "$ref": "#\/components\/schemas\/HsCodeResource" } }, "meta": { "$ref": "#\/components\/schemas\/OffsetPaginationResource" } }, "required": [ "data", "meta" ], "title": "HsCodeSearchResource" }, "MessageResource": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "title": "MessageResource" }, "MoneyResource": { "type": "object", "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ], "title": "MoneyResource" }, "NormalizeAddressCommand": { "type": "object", "properties": { "address": { "type": "string", "minLength": 2, "maxLength": 255 }, "city": { "type": [ "string", "null" ], "maxLength": 100 }, "postal_code": { "type": [ "string", "null" ], "maxLength": 20 }, "country": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 }, "provider": { "type": [ "string", "null" ] }, "api_key": { "type": [ "string", "null" ], "maxLength": 500 }, "model": { "type": [ "string", "null" ], "maxLength": 100 }, "account_id": { "type": [ "string", "null" ], "maxLength": 100 } }, "required": [ "address" ], "title": "NormalizeAddressCommand" }, "NormalizedAddressFieldsResource": { "type": "object", "properties": { "address": { "type": [ "string", "null" ], "description": "Normalized address line when supplied or resolved." }, "city": { "type": [ "string", "null" ], "description": "Normalized city when supplied or resolved." }, "postal_code": { "type": [ "string", "null" ], "description": "Normalized postal code when supplied or resolved.", "example": "1000" }, "country": { "type": [ "string", "null" ], "description": "Normalized ISO 3166-1 alpha-2 country code when supplied or resolved.", "example": "BG" } }, "required": [ "address", "city", "postal_code", "country" ], "title": "NormalizedAddressFieldsResource" }, "NormalizedAddressResource": { "type": "object", "properties": { "normalized": { "type": "boolean", "description": "Whether a provider produced a result above the configured confidence threshold." }, "address": { "$ref": "#\/components\/schemas\/NormalizedAddressFieldsResource" }, "confidence": { "type": "number", "description": "Selected result confidence from 0 to 1.", "example": 0.92 }, "provider": { "type": [ "string", "null" ], "description": "Normalization provider, or null when the original input is returned.", "example": "openai" } }, "required": [ "normalized", "address", "confidence", "provider" ], "title": "NormalizedAddressResource" }, "OffsetPaginationResource": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total matching records across all pages.", "example": 42 }, "limit": { "type": "integer", "description": "Maximum records returned in this page.", "example": 20 }, "offset": { "type": "integer", "description": "Zero-based record offset for this page.", "example": 0 } }, "required": [ "total", "limit", "offset" ], "title": "OffsetPaginationResource" }, "OnboardingConciergeResource": { "type": "object", "properties": { "pending": { "type": "boolean" }, "status": { "type": [ "string", "null" ], "enum": [ "pending", "handled", null ] }, "requested_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "pending", "status", "requested_at" ], "title": "OnboardingConciergeResource" }, "ParcelData": { "type": "object", "properties": { "weight": { "type": "number" }, "length": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "count": { "type": "integer" }, "description": { "type": "string" } }, "title": "ParcelData" }, "PickupPointNameResource": { "type": "object", "properties": { "bg": { "type": "string", "description": "Carrier-provided Bulgarian or primary pickup-point name." }, "en": { "type": "string", "description": "Carrier-provided English name, omitted when unavailable." } }, "required": [ "bg" ], "title": "PickupPointNameResource" }, "PickupPointProviderResource": { "type": "object", "properties": { "carrier": { "type": "string", "description": "Stable carrier slug.", "enum": [ "speedy", "econt", "boxnow", "postone", "direx", "sameday", "bgpost", "a1post", "pigeon" ], "example": "speedy" }, "types": { "type": "array", "description": "Available pickup-point types, such as office or locker.", "items": { "$ref": "#\/components\/schemas\/PickupPointType" } }, "count": { "type": "integer", "description": "Number of active pickup points currently available.", "example": 1250 } }, "required": [ "carrier", "types", "count" ], "title": "PickupPointProviderResource" }, "PickupPointProvidersResource": { "type": "object", "properties": { "data": { "type": "array", "description": "Carriers with active pickup-point coverage.", "items": { "$ref": "#\/components\/schemas\/PickupPointProviderResource" } } }, "required": [ "data" ], "title": "PickupPointProvidersResource" }, "PickupPointResource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ShipBG pickup-point UUID." }, "carrier": { "type": "string", "description": "Stable carrier slug.", "enum": [ "speedy", "econt", "boxnow", "postone", "direx", "sameday", "bgpost", "a1post", "pigeon" ], "example": "econt" }, "carrier_point_id": { "type": "string", "description": "Carrier-native pickup-point identifier.", "example": "34673" }, "code": { "type": [ "string", "null" ], "description": "Carrier-native office code when the carrier distinguishes it from the point identifier.", "example": "9048" }, "name": { "$ref": "#\/components\/schemas\/PickupPointNameResource" }, "type": { "type": "string", "description": "Pickup-point delivery type.", "enum": [ "office", "locker", "postbox" ] }, "address": { "type": "string", "description": "Human-readable street address." }, "city": { "type": "string", "description": "City or locality name." }, "postal_code": { "type": "string", "description": "Postal code supplied by the carrier.", "example": "1000" }, "coordinates": { "anyOf": [ { "$ref": "#\/components\/schemas\/CoordinatesResource" }, { "type": "null" } ] }, "is_active": { "type": "boolean", "description": "Whether the pickup point is currently available for selection." } }, "required": [ "id", "carrier", "carrier_point_id", "code", "name", "type", "address", "city", "postal_code", "coordinates", "is_active" ], "title": "PickupPointResource" }, "PickupPointSearchResource": { "type": "object", "properties": { "data": { "type": "array", "description": "Active pickup points matching the requested location and filters.", "items": { "$ref": "#\/components\/schemas\/PickupPointResource" } }, "meta": { "$ref": "#\/components\/schemas\/OffsetPaginationResource" }, "reason": { "type": "string", "enum": [ "no_results_in_radius", "no_results_in_city", "no_results_for_filters" ] } }, "required": [ "data", "meta" ], "title": "PickupPointSearchResource" }, "PickupPointType": { "type": "string", "enum": [ "office", "locker", "postbox" ], "title": "PickupPointType" }, "PickupResource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Pickup request UUID." }, "carrier": { "type": "string", "description": "Stable carrier slug.", "enum": [ "speedy", "econt", "boxnow", "postone", "direx", "sameday", "bgpost", "a1post", "pigeon" ], "example": "speedy" }, "carrier_pickup_id": { "type": [ "string", "null" ], "description": "Carrier-native pickup request identifier." }, "status": { "type": "string", "description": "Pickup request lifecycle status.", "enum": [ "scheduled", "cancelled", "completed" ] }, "pickup_date": { "type": "string", "format": "date", "description": "Requested pickup date.", "example": "2026-08-14" }, "time_window": { "$ref": "#\/components\/schemas\/PickupTimeWindowResource" }, "shipment_count": { "type": "integer", "description": "Number of shipments included.", "example": 2 }, "shipment_ids": { "type": "array", "description": "Shipment UUIDs included in this pickup.", "items": { "type": "string", "format": "uuid" } }, "address": { "type": "object", "description": "Stored pickup address. Legacy rows may omit unavailable keys.", "properties": { "name": { "type": "string" }, "company": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "country_code": { "type": "string" }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "street": { "type": "string" }, "street_number": { "type": "string" }, "address_line": { "type": "string" } } }, "contact": { "type": "object", "description": "Carrier pickup contact.", "properties": { "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "name", "phone" ] }, "note": { "type": [ "string", "null" ], "description": "Pickup note passed to the carrier." }, "confirmation": { "type": [ "string", "null" ], "description": "Carrier confirmation message, when supplied." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Pickup request creation time." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Pickup request last-update time." } }, "required": [ "id", "carrier", "carrier_pickup_id", "status", "pickup_date", "time_window", "shipment_count", "shipment_ids", "address", "contact", "note", "confirmation", "created_at", "updated_at" ], "title": "PickupResource" }, "PickupTimeWindowResource": { "type": "object", "properties": { "from": { "type": "string", "description": "Requested pickup-window start in 24-hour `HH:MM` format.", "example": "09:00" }, "to": { "type": "string", "description": "Requested pickup-window end in 24-hour `HH:MM` format.", "example": "18:00" } }, "required": [ "from", "to" ], "title": "PickupTimeWindowResource" }, "PlanResource": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "price_cents": { "type": "integer", "description": "Monthly price in the currency minor unit.", "example": 4900 }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "example": "BGN" }, "monthly_shipments_limit": { "type": "integer" }, "features": { "type": "array", "items": { "type": "string" } } }, "required": [ "slug", "name", "description", "price_cents", "currency", "monthly_shipments_limit", "features" ], "title": "PlanResource" }, "PlansResponseResource": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/PlanResource" } } }, "required": [ "data" ], "title": "PlansResponseResource" }, "PricingActionResource": { "type": "object", "properties": { "type": { "type": "string", "description": "Pricing transformation applied when all rule conditions match.", "enum": [ "free_shipping", "flat_rate", "percentage_discount", "fixed_discount", "merchant_subsidy" ] }, "value": { "description": "Amount in minor units or percentage points, depending on action type.", "anyOf": [ { "type": "integer" }, { "type": "number" }, { "type": "null" } ] }, "unit": { "type": [ "string", "null" ], "description": "Value unit when the action requires one.", "enum": [ "fixed", "percent", null ] } }, "required": [ "type" ], "title": "PricingActionResource" }, "PricingConditionResource": { "type": "object", "properties": { "field": { "type": "string", "description": "Order or delivery fact tested by this condition.", "enum": [ "order_total", "order_weight", "product_category", "product_shipping_class", "carrier", "delivery_type" ] }, "operator": { "type": "string", "description": "Comparison operator.", "enum": [ "=", "!=", ">", ">=", "<", "<=", "in", "not_in", "contains" ] }, "value": { "description": "Comparison value; JSON type depends on the selected field and operator." } }, "required": [ "field", "operator", "value" ], "title": "PricingConditionResource" }, "PricingRuleResource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Pricing rule UUID." }, "name": { "type": "string", "description": "Merchant-defined rule name." }, "enabled": { "type": "boolean", "description": "Whether the rule participates in evaluation." }, "priority": { "type": "integer", "description": "Lower values are evaluated first.", "example": 10 }, "stop_on_match": { "type": "boolean", "description": "Whether evaluation stops after this rule matches." }, "conditions": { "type": "array", "description": "Conditions that must all match.", "items": { "$ref": "#\/components\/schemas\/PricingConditionResource" } }, "actions": { "type": "array", "description": "Exactly one pricing action for the current contract.", "items": { "$ref": "#\/components\/schemas\/PricingActionResource" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Rule creation time." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Rule last-update time." } }, "required": [ "id", "name", "enabled", "priority", "stop_on_match", "conditions", "actions", "created_at", "updated_at" ], "title": "PricingRuleResource" }, "PricingRuleTemplateListResource": { "type": "object", "properties": { "data": { "type": "array", "description": "Available localized pricing-rule templates.", "items": { "$ref": "#\/components\/schemas\/PricingRuleTemplateResource" } } }, "required": [ "data" ], "title": "PricingRuleTemplateListResource" }, "PricingRuleTemplateResource": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable template identifier.", "example": "free_shipping_over_50" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string", "enum": [ "promotion", "pickup", "flat", "discount", "subsidy" ] }, "required_any_carrier": { "type": "array", "description": "Carrier accounts of which at least one is required; empty means carrier-independent.", "items": { "$ref": "#\/components\/schemas\/CarrierSlug" } }, "suggested_priority": { "type": "integer", "description": "Suggested rule priority; lower values evaluate first." }, "stop_on_match": { "type": "boolean" }, "conditions": { "type": "array", "description": "Pre-filled rule conditions.", "items": { "$ref": "#\/components\/schemas\/PricingConditionResource" } }, "actions": { "type": "array", "description": "Pre-filled pricing action.", "items": { "$ref": "#\/components\/schemas\/PricingActionResource" } } }, "required": [ "id", "name", "description", "category", "required_any_carrier", "suggested_priority", "stop_on_match", "conditions", "actions" ], "title": "PricingRuleTemplateResource" }, "ProblemDetailViolationResource": { "type": "object", "properties": { "field": { "type": "string", "description": "Request field or parameter associated with the error.", "example": "recipient.postal_code" }, "code": { "type": "string", "description": "Stable machine-readable error code.", "example": "validation_failed" }, "message": { "type": "string", "description": "Human-readable explanation.", "example": "The recipient postal code field is required." } }, "required": [ "field", "code", "message" ], "title": "ProblemDetailViolationResource" }, "ProblemDetailsResource": { "type": "object", "properties": { "type": { "type": "string", "format": "uri", "description": "Absolute URI identifying the problem type.", "example": "https:\/\/shipbg.com\/errors\/validation_failed" }, "title": { "type": "string", "example": "Validation failed" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": [ "string", "null" ], "example": "The given data was invalid." }, "instance": { "type": "string", "description": "Path of the request instance that failed.", "example": "\/api\/v1\/shipments" }, "trace_id": { "type": [ "string", "null" ], "format": "uuid", "description": "ShipBG request trace UUID when request logging created one." }, "errors": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ProblemDetailViolationResource" } } }, "required": [ "type", "title", "status", "detail", "instance", "trace_id" ], "title": "ProblemDetailsResource" }, "QuoteRatesCommand": { "type": "object", "properties": { "from_address": { "$ref": "#\/components\/schemas\/AddressData" }, "to_address": { "$ref": "#\/components\/schemas\/AddressData" }, "parcel": { "$ref": "#\/components\/schemas\/ParcelData" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "carriers": { "type": "array", "items": { "type": "string" } }, "options": { "anyOf": [ { "$ref": "#\/components\/schemas\/ShipmentOptionsData" }, { "type": "null" } ] }, "carrier_options": { "anyOf": [ { "$ref": "#\/components\/schemas\/CarrierOptionsData" }, { "type": "null" } ] }, "order_total": { "type": [ "integer", "null" ], "minimum": 0 }, "product_categories": { "type": [ "array", "null" ], "items": { "type": "string" } }, "product_shipping_classes": { "type": [ "array", "null" ], "items": { "type": "string" } }, "user_id": { "type": [ "string", "null" ], "format": "uuid" }, "domain_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "from_address", "to_address", "parcel" ], "title": "QuoteRatesCommand" }, "RateErrorResource": { "type": "object", "properties": { "carrier": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "carrier", "code", "message" ], "title": "RateErrorResource" }, "RateOptionResource": { "type": "object", "properties": { "carrier": { "type": "string", "description": "Stable carrier slug.", "example": "speedy" }, "carrier_account_id": { "type": [ "string", "null" ], "description": "Courier account UUID that must be carried into shipment creation to preserve the quoted carrier contract." }, "service_code": { "type": "string", "description": "Carrier service identifier.", "example": "505" }, "service_label": { "type": "string", "description": "Human-readable carrier service name.", "example": "Standard 24 hours" }, "amount": { "type": "integer", "description": "Quoted price in ISO 4217 minor units.", "example": 850 }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "example": "BGN" }, "delivery_type": { "type": [ "string", "null" ], "description": "Canonical delivery type, when known.", "example": "home_delivery" }, "estimated_delivery_days": { "type": [ "integer", "null" ], "description": "Estimated whole delivery days, when supplied by the carrier.", "example": 2 }, "applied_rules": { "type": "array", "description": "Pricing rules applied after the carrier returned its quote.", "items": { "$ref": "#\/components\/schemas\/AppliedPricingRuleResource" } }, "rate_source": { "type": "string", "description": "Price provenance: carrier quote or a ShipBG pricing rule.", "example": "carrier" } }, "required": [ "carrier", "carrier_account_id", "service_code", "service_label", "amount", "currency", "delivery_type", "estimated_delivery_days", "applied_rules", "rate_source" ], "title": "RateOptionResource" }, "RateQuoteResource": { "type": "object", "properties": { "rates": { "type": "array", "description": "Successful carrier quotes.", "items": { "$ref": "#\/components\/schemas\/RateOptionResource" } }, "errors": { "type": "array", "description": "Per-carrier failures that did not prevent other quotes.", "items": { "$ref": "#\/components\/schemas\/RateErrorResource" } }, "currency": { "type": "string" } }, "required": [ "rates", "errors", "currency" ], "title": "RateQuoteResource" }, "ReturnShipmentListResource": { "type": "object", "properties": { "data": { "type": "array", "description": "Returns matching the requested filters.", "items": { "$ref": "#\/components\/schemas\/ReturnShipmentResource" } }, "meta": { "$ref": "#\/components\/schemas\/CursorPaginationResource" } }, "required": [ "data", "meta" ], "title": "ReturnShipmentListResource" }, "ReturnShipmentResource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Return-shipment UUID." }, "original_shipment_id": { "type": "string", "format": "uuid", "description": "Original outbound shipment UUID." }, "carrier": { "type": "string", "description": "Stable carrier slug.", "enum": [ "speedy", "econt", "boxnow", "postone", "direx", "sameday", "bgpost", "a1post", "pigeon" ], "example": "speedy" }, "status": { "type": "string", "description": "Return lifecycle status.", "enum": [ "created", "labelled", "in_transit", "delivered", "cancelled", "failed" ] }, "label_ready": { "type": "boolean", "description": "Whether the return-label endpoint can currently serve a PDF." }, "replaced_status": { "type": "string", "description": "Outbound shipment status replaced when the return was created.", "enum": [ "draft", "persisted", "labelled", "in_transit", "delivered", "returned", "cancelled", "failed" ] }, "return_type": { "type": [ "string", "null" ], "description": "Carrier return type when supplied." }, "pickup_type": { "type": [ "string", "null" ], "description": "Requested return pickup mode.", "enum": [ "address", "office", "locker", null ] }, "tracking_code": { "type": [ "string", "null" ], "description": "Carrier tracking code, when assigned." }, "carrier_shipment_id": { "type": [ "string", "null" ], "description": "Carrier-native return shipment identifier, when assigned." }, "service_code": { "type": [ "string", "null" ], "description": "Carrier service identifier." }, "return_reason": { "type": "string", "description": "Reason supplied when the return was created." }, "notes": { "type": [ "string", "null" ], "description": "Additional return notes." }, "label_url": { "type": [ "string", "null" ], "description": "ShipBG return-label URL when a materialized label exists." }, "from_address": { "anyOf": [ { "$ref": "#\/components\/schemas\/ShipmentAddressResource" }, { "type": "null" } ] }, "to_address": { "anyOf": [ { "$ref": "#\/components\/schemas\/ShipmentAddressResource" }, { "type": "null" } ] }, "parcel": { "anyOf": [ { "$ref": "#\/components\/schemas\/ShipmentParcelResource" }, { "type": "null" } ] }, "order_ref": { "type": [ "string", "null" ], "description": "Client order reference inherited from the original shipment." }, "rate": { "anyOf": [ { "$ref": "#\/components\/schemas\/ShipmentMoneyResource" }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Return creation time." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Return last-update time." } }, "required": [ "id", "original_shipment_id", "carrier", "status", "label_ready", "replaced_status", "return_type", "pickup_type", "tracking_code", "carrier_shipment_id", "service_code", "return_reason", "notes", "label_url", "from_address", "to_address", "parcel", "order_ref", "rate", "created_at", "updated_at" ], "title": "ReturnShipmentResource" }, "ShipmentAddressResource": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Contact name." }, "company": { "type": [ "string", "null" ], "description": "Company name, when applicable." }, "phone": { "type": [ "string", "null" ], "description": "Contact telephone number." }, "email": { "type": [ "string", "null" ], "description": "Contact email address." }, "country_code": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code.", "example": "BG" }, "postal_code": { "type": [ "string", "null" ], "description": "Postal code.", "example": "1000" }, "city": { "type": [ "string", "null" ], "description": "City or locality." }, "region": { "type": [ "string", "null" ], "description": "Region, province, or state." }, "street": { "type": [ "string", "null" ], "description": "Street name." }, "street_number": { "type": [ "string", "null" ], "description": "Street or building number." }, "address_line": { "type": [ "string", "null" ], "description": "Free-form address line when structured street fields are unavailable." } }, "required": [ "name", "company", "phone", "email", "country_code", "postal_code", "city", "region", "street", "street_number", "address_line" ], "title": "ShipmentAddressResource" }, "ShipmentCarrierOptionsResource": { "type": "object", "properties": { "speedy": { "description": "Speedy-specific options echoed from shipment creation." }, "econt": { "description": "Econt-specific options echoed from shipment creation." }, "boxnow": { "description": "BoxNow-specific options echoed from shipment creation." }, "postone": { "description": "PostOne-specific options echoed from shipment creation." }, "direx": { "description": "Direx-specific options echoed from shipment creation." }, "sameday": { "description": "Sameday-specific options echoed from shipment creation." }, "bgpost": { "description": "Bulgarian Posts-specific options echoed from shipment creation." }, "a1post": { "description": "A1 Post-specific options echoed from shipment creation." }, "pigeon": { "description": "Pigeon-specific options echoed from shipment creation." } }, "required": [ "speedy", "econt", "boxnow", "postone", "direx", "sameday", "bgpost", "a1post", "pigeon" ], "title": "ShipmentCarrierOptionsResource" }, "ShipmentListResource": { "type": "object", "properties": { "data": { "type": "array", "description": "Shipments in reverse chronological order.", "items": { "$ref": "#\/components\/schemas\/ShipmentResource" } }, "meta": { "$ref": "#\/components\/schemas\/CursorPaginationResource" } }, "required": [ "data", "meta" ], "title": "ShipmentListResource" }, "ShipmentMoneyResource": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in ISO 4217 minor units.", "example": 850 }, "currency": { "type": [ "string", "null" ], "description": "ISO 4217 currency code.", "example": "BGN" } }, "required": [ "amount", "currency" ], "title": "ShipmentMoneyResource" }, "ShipmentOptionsData": { "type": "object", "properties": { "note": { "type": "string" }, "saturday_delivery": { "type": "boolean" }, "declared_value": { "type": "integer" }, "declared_value_currency": { "type": "string" }, "fragile": { "type": "boolean" }, "document": { "type": "boolean" }, "cod_amount": { "type": "integer" }, "cod_currency": { "type": "string" } }, "title": "ShipmentOptionsData" }, "ShipmentOptionsResource": { "type": "object", "properties": { "note": { "type": [ "string", "null" ], "description": "Delivery note passed to the carrier when supported." }, "saturday_delivery": { "type": [ "boolean", "null" ], "description": "Whether Saturday delivery was requested." }, "declared_value": { "type": [ "integer", "null" ], "description": "Declared parcel value in ISO 4217 minor units.", "example": 12000 }, "declared_value_currency": { "type": [ "string", "null" ], "description": "ISO 4217 currency for the declared value.", "example": "BGN" }, "fragile": { "type": [ "boolean", "null" ], "description": "Whether fragile handling was requested." }, "document": { "type": [ "boolean", "null" ], "description": "Whether the shipment contains documents." }, "cod_amount": { "type": [ "integer", "null" ], "description": "Cash-on-delivery amount in ISO 4217 minor units.", "example": 1600 }, "cod_currency": { "type": [ "string", "null" ], "description": "ISO 4217 currency for the cash-on-delivery amount.", "example": "BGN" } }, "required": [ "note", "saturday_delivery", "declared_value", "declared_value_currency", "fragile", "document", "cod_amount", "cod_currency" ], "title": "ShipmentOptionsResource" }, "ShipmentParcelResource": { "type": "object", "properties": { "weight": { "type": [ "number", "null" ], "description": "Parcel weight in kilograms.", "example": 1.5 }, "length": { "type": [ "number", "null" ], "description": "Parcel length in centimetres.", "example": 30 }, "width": { "type": [ "number", "null" ], "description": "Parcel width in centimetres.", "example": 20 }, "height": { "type": [ "number", "null" ], "description": "Parcel height in centimetres.", "example": 10 }, "count": { "type": [ "integer", "null" ], "description": "Number of parcels represented by the shipment.", "example": 1 }, "description": { "type": [ "string", "null" ], "description": "Human-readable parcel contents description." } }, "required": [ "weight", "length", "width", "height", "count", "description" ], "title": "ShipmentParcelResource" }, "ShipmentRateResource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Stored rate UUID." }, "carrier": { "type": "string", "description": "Stable carrier slug.", "example": "speedy" }, "service_code": { "type": "string", "description": "Carrier service identifier.", "example": "505" }, "service_label": { "type": [ "string", "null" ], "description": "Human-readable carrier service name." }, "amount": { "type": "integer", "description": "Selected carrier price in ISO 4217 minor units.", "example": 850 }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "example": "BGN" }, "delivery_type": { "type": [ "string", "null" ], "description": "Canonical delivery type, when known.", "example": "home_delivery" }, "estimated_delivery_days": { "type": [ "integer", "null" ], "description": "Estimated whole delivery days, when supplied by the carrier.", "example": 2 }, "is_selected": { "type": "boolean", "description": "Whether this rate was selected for the shipment." } }, "required": [ "id", "carrier", "service_code", "service_label", "amount", "currency", "delivery_type", "estimated_delivery_days", "is_selected" ], "title": "ShipmentRateResource" }, "ShipmentResource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Shipment UUID." }, "carrier": { "type": "string", "description": "Stable carrier slug.", "enum": [ "speedy", "econt", "boxnow", "postone", "direx", "sameday", "bgpost", "a1post", "pigeon" ], "example": "speedy" }, "status": { "type": "string", "description": "Canonical shipment lifecycle status.", "enum": [ "draft", "persisted", "labelled", "in_transit", "delivered", "returned", "cancelled", "failed" ] }, "label_ready": { "type": "boolean", "description": "Whether the label download endpoint can currently serve this shipment label." }, "tracking_code": { "type": [ "string", "null" ], "description": "Carrier tracking code, when assigned." }, "carrier_shipment_id": { "type": [ "string", "null" ], "description": "Carrier-native shipment identifier, when assigned." }, "service_code": { "type": [ "string", "null" ], "description": "Carrier service identifier.", "example": "505" }, "service_name": { "type": [ "string", "null" ], "description": "Human-readable carrier service name, when a selected stored rate is available." }, "order_ref": { "type": [ "string", "null" ], "description": "Client order reference." }, "pickup_point_id": { "type": [ "string", "null" ], "description": "Selected pickup-point identifier when represented separately; otherwise null." }, "sender": { "anyOf": [ { "$ref": "#\/components\/schemas\/ShipmentAddressResource" }, { "type": "null" } ] }, "recipient": { "anyOf": [ { "$ref": "#\/components\/schemas\/ShipmentAddressResource" }, { "type": "null" } ] }, "parcel": { "anyOf": [ { "$ref": "#\/components\/schemas\/ShipmentParcelResource" }, { "type": "null" } ] }, "options": { "anyOf": [ { "$ref": "#\/components\/schemas\/ShipmentOptionsResource" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "carrier_options": { "anyOf": [ { "$ref": "#\/components\/schemas\/ShipmentCarrierOptionsResource" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "rate": { "anyOf": [ { "$ref": "#\/components\/schemas\/ShipmentMoneyResource" }, { "type": "null" } ] }, "estimated_days": { "type": [ "integer", "null" ], "description": "Estimated whole delivery days, when supplied by the selected rate." }, "label_url": { "type": [ "string", "null" ], "description": "ShipBG label URL when a materialized label exists." }, "label_format": { "type": [ "string", "null" ], "description": "Label format when known; currently null for lifecycle responses." }, "selected_rate": { "anyOf": [ { "$ref": "#\/components\/schemas\/ShipmentRateResource" }, { "type": "null" } ] }, "carrier_capabilities": { "type": "array", "description": "Reserved capability identifiers returned for this shipment.", "items": { "type": "string" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Shipment creation time." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Shipment last-update time." }, "rates": { "description": "Stored rates, emitted only when `include=rates` was requested.", "anyOf": [ { "type": "array", "items": { "$ref": "#\/components\/schemas\/ShipmentRateResource" } }, { "type": "object" } ] }, "tracking_events": { "description": "Tracking timeline, emitted only when `include=tracking_events` was requested.", "anyOf": [ { "type": "array", "items": { "$ref": "#\/components\/schemas\/TrackingEventResource" } }, { "type": "object" } ] } }, "required": [ "id", "carrier", "status", "label_ready", "tracking_code", "carrier_shipment_id", "service_code", "service_name", "order_ref", "pickup_point_id", "sender", "recipient", "parcel", "options", "carrier_options", "rate", "estimated_days", "label_url", "label_format", "selected_rate", "carrier_capabilities", "created_at", "updated_at" ], "title": "ShipmentResource" }, "TestCarrierConnectionCommand": { "type": "object", "properties": { "carrier_account_id": { "type": [ "string", "null" ], "format": "uuid" }, "carrier": { "type": [ "string", "null" ] }, "credentials": { "type": [ "array", "null" ], "items": { "type": "string" } }, "is_test": { "type": [ "boolean", "null" ] } }, "title": "TestCarrierConnectionCommand" }, "TrackingEventResource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Tracking-event UUID." }, "shipment_id": { "type": "string", "format": "uuid", "description": "Shipment UUID." }, "status": { "type": "string", "description": "Canonical ShipBG tracking status.", "enum": [ "unknown", "registered", "accepted", "picked_up", "in_transit", "out_for_delivery", "delivered", "failed_delivery", "returned", "cancelled" ] }, "description": { "type": [ "string", "null" ], "description": "Carrier-provided event description." }, "location": { "type": [ "string", "null" ], "description": "Carrier-provided event location." }, "occurred_at": { "type": "string", "format": "date-time", "description": "Time the carrier says the event occurred." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time ShipBG first recorded the event." } }, "required": [ "id", "shipment_id", "status", "description", "location", "occurred_at", "created_at" ], "title": "TrackingEventResource" }, "TrackingTimelineResource": { "type": "object", "properties": { "data": { "type": "array", "description": "Tracking events ordered newest first.", "items": { "$ref": "#\/components\/schemas\/TrackingEventResource" } }, "meta": { "$ref": "#\/components\/schemas\/CursorPaginationResource" } }, "required": [ "data", "meta" ], "title": "TrackingTimelineResource" }, "UpdateCarrierAccountCommand": { "type": "object", "properties": { "carrier_account_id": { "type": "string", "format": "uuid" }, "credentials": { "type": [ "array", "null" ], "items": { "type": "string" } }, "settings": { "type": [ "array", "null" ], "items": { "type": "string" } }, "is_active": { "type": [ "boolean", "null" ] }, "is_test": { "type": [ "boolean", "null" ] }, "user_id": { "type": [ "string", "null" ], "format": "uuid" } }, "title": "UpdateCarrierAccountCommand" }, "UpdateCarrierRoutingCommand": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#\/components\/schemas\/CarrierRoutingEntry" } }, "domain_id": { "type": [ "string", "null" ], "format": "uuid" }, "user_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "rules" ], "title": "UpdateCarrierRoutingCommand" }, "WebhookAttemptResource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event": { "type": "string", "enum": [ "shipment.created", "shipment.status_changed", "shipment.delivered", "shipment.failed", "tracking.updated", "label.ready" ] }, "delivery_id": { "type": "string", "format": "uuid" }, "response_status": { "type": [ "integer", "null" ] }, "attempt_number": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed" ] }, "attempted_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_retry_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "payload": { "description": "Exact signed outbound payload. Known envelope and event payload fields are typed; an open object preserves legacy\/forward-compatible attempts.", "anyOf": [ { "$ref": "#\/components\/schemas\/WebhookEnvelopeResource" }, { "type": "object", "additionalProperties": {} } ] } }, "required": [ "id", "event", "delivery_id", "response_status", "attempt_number", "status", "attempted_at", "next_retry_at", "created_at", "payload" ], "title": "WebhookAttemptResource" }, "WebhookEnvelopeResource": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique ShipBG event identifier." }, "event": { "type": "string", "enum": [ "shipment.created", "shipment.status_changed", "shipment.delivered", "shipment.failed", "tracking.updated", "label.ready" ] }, "delivery_id": { "type": "string", "format": "uuid", "description": "Delivery UUID. Test-delivery payloads omit this field." }, "created_at": { "type": "string", "format": "date-time" }, "data": { "description": "Event-specific payload. Known ShipBG event payloads are typed; the open object preserves forward compatibility for newly introduced event variants.", "anyOf": [ { "$ref": "#\/components\/schemas\/WebhookShipmentCreatedDataResource" }, { "$ref": "#\/components\/schemas\/WebhookShipmentStatusChangedDataResource" }, { "$ref": "#\/components\/schemas\/WebhookTrackingUpdatedDataResource" }, { "$ref": "#\/components\/schemas\/WebhookLabelReadyDataResource" }, { "$ref": "#\/components\/schemas\/WebhookTestDataResource" }, { "type": "object", "additionalProperties": {} } ] } }, "required": [ "id", "event", "created_at", "data" ], "title": "WebhookEnvelopeResource" }, "WebhookLabelReadyDataResource": { "type": "object", "properties": { "shipment_id": { "type": "string", "format": "uuid" }, "label_url": { "type": "string", "format": "uri" }, "generated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "shipment_id", "label_url", "generated_at" ], "title": "WebhookLabelReadyDataResource" }, "WebhookShipmentCreatedDataResource": { "type": "object", "properties": { "shipment_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft", "persisted", "labelled", "in_transit", "delivered", "returned", "cancelled", "failed" ] }, "tracking_code": { "type": [ "string", "null" ] }, "carrier_slug": { "type": "string", "enum": [ "speedy", "econt", "boxnow", "postone", "direx", "sameday", "bgpost", "a1post", "pigeon" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "shipment_id", "status", "tracking_code", "carrier_slug", "created_at" ], "title": "WebhookShipmentCreatedDataResource" }, "WebhookShipmentStatusChangedDataResource": { "type": "object", "properties": { "shipment_id": { "type": "string", "format": "uuid" }, "old_status": { "type": "string", "enum": [ "draft", "persisted", "labelled", "in_transit", "delivered", "returned", "cancelled", "failed" ] }, "new_status": { "type": "string", "enum": [ "draft", "persisted", "labelled", "in_transit", "delivered", "returned", "cancelled", "failed" ] }, "changed_at": { "type": "string", "format": "date-time" } }, "required": [ "shipment_id", "old_status", "new_status", "changed_at" ], "title": "WebhookShipmentStatusChangedDataResource" }, "WebhookSubscriptionCreatedResource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "shipment.created", "shipment.status_changed", "shipment.delivered", "shipment.failed", "tracking.updated", "label.ready" ] } }, "is_active": { "type": "boolean" }, "has_secret": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "secret": { "type": "string", "description": "Plaintext HMAC signing secret shown exactly once. Store it securely before discarding this response." } }, "required": [ "id", "url", "events", "is_active", "has_secret", "created_at", "updated_at", "secret" ], "title": "WebhookSubscriptionCreatedResource" }, "WebhookSubscriptionResource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint that receives signed webhook POST requests." }, "events": { "type": "array", "description": "Subscribed ShipBG event names.", "items": { "type": "string", "enum": [ "shipment.created", "shipment.status_changed", "shipment.delivered", "shipment.failed", "tracking.updated", "label.ready" ] } }, "is_active": { "type": "boolean" }, "has_secret": { "type": "boolean", "description": "Whether a signing secret is configured; the secret value is returned only at creation." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "url", "events", "is_active", "has_secret", "created_at", "updated_at" ], "title": "WebhookSubscriptionResource" }, "WebhookTestDataResource": { "type": "object", "properties": { "test": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "test", "message" ], "title": "WebhookTestDataResource" }, "WebhookTestResultResource": { "type": "object", "properties": { "delivery_id": { "type": "string", "format": "uuid" }, "success": { "type": "boolean" }, "response_status": { "type": "integer", "description": "Receiver HTTP status, or 0 when no HTTP response was received." }, "duration_ms": { "type": "integer" }, "response_body_preview": { "type": "string", "description": "First 1024 bytes of the receiver response body." } }, "required": [ "delivery_id", "success", "response_status", "duration_ms", "response_body_preview" ], "title": "WebhookTestResultResource" }, "WebhookTrackingEventDataResource": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "unknown", "registered", "accepted", "picked_up", "in_transit", "out_for_delivery", "delivered", "failed_delivery", "returned", "cancelled" ] }, "location": { "type": [ "string", "null" ] }, "occurred_at": { "type": "string", "format": "date-time" } }, "required": [ "status", "location", "occurred_at" ], "title": "WebhookTrackingEventDataResource" }, "WebhookTrackingUpdatedDataResource": { "type": "object", "properties": { "shipment_id": { "type": "string", "format": "uuid" }, "event": { "$ref": "#\/components\/schemas\/WebhookTrackingEventDataResource" } }, "required": [ "shipment_id", "event" ], "title": "WebhookTrackingUpdatedDataResource" } }, "responses": { "ValidationException": { "description": "The request failed validation.", "content": { "application\/problem+json": { "schema": { "$ref": "#\/components\/schemas\/ProblemDetailsResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "AuthenticationException": { "description": "Authentication is missing or invalid.", "content": { "application\/problem+json": { "schema": { "$ref": "#\/components\/schemas\/ProblemDetailsResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "ModelNotFoundException": { "description": "The requested resource was not found or is not visible to this integration.", "content": { "application\/problem+json": { "schema": { "$ref": "#\/components\/schemas\/ProblemDetailsResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "AuthorizationException": { "description": "The authenticated integration is not allowed to perform this operation.", "content": { "application\/problem+json": { "schema": { "$ref": "#\/components\/schemas\/ProblemDetailsResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "ConflictException": { "description": "The requested operation conflicts with the current resource state.", "content": { "application\/problem+json": { "schema": { "$ref": "#\/components\/schemas\/ProblemDetailsResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } }, "ThrottleRequestsException": { "description": "The request rate limit was exceeded.", "content": { "application\/problem+json": { "schema": { "$ref": "#\/components\/schemas\/ProblemDetailsResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } } }, "InternalServerError": { "description": "An unexpected server error occurred.", "content": { "application\/problem+json": { "schema": { "$ref": "#\/components\/schemas\/ProblemDetailsResource" } } }, "headers": { "ShipBG-API-Version": { "description": "Backend-assigned API contract used for this response.", "schema": { "type": "string", "enum": [ "2026-07", "2026-08-06" ] } }, "ShipBG-Integration-ID": { "description": "Resolved integration UUID when the request was associated with an API integration.", "schema": { "type": "string", "format": "uuid" } } } } } } }