{ "openapi": "3.1.0", "servers": [ { "url": "https://weshipyou.com/api/v1", "description": "Live" }, { "url": "https://sandbox.weshipyou.com/api/v1", "description": "Sandbox" } ], "info": { "description": "The WeShipYou API is organized around [REST](https://en.wikipedia.org/wiki/REST). It has predictable, resource-oriented URLs, accepts JSON request bodies, returns JSON responses and uses standard HTTP status codes and verbs.\n\n# Test and live\n\nTry your integration against the **Sandbox** server (`sandbox.weshipyou.com`) first: nothing you do there reaches a real carrier or moves real money. The **Live** server (`weshipyou.com`) is real: labels bought there are charged to your wallet.\n\nThe API works on one object per request; there are no bulk updates.\n\n# OpenAPI\n\nThis reference is generated from an **OpenAPI 3.1** document. Download it from [/docs/api/openapi.json](/docs/api/openapi.json) and import it into Postman or any OpenAPI tool.\n\n# Cross-origin requests\n\nThe API supports [CORS](https://www.w3.org/TR/cors/) for every origin, so you can call it from a browser. Never put an access token in code that other people can read.\n\n# Authentication\n\nThe API authenticates every request with a **JSON Web Token (JWT)**. There are no API keys.\n\n1. Call `POST /authentication` with your WeShipYou username (or email) and password. If two-factor authentication is on for your user, also send the current 6-digit code from your authenticator app as `twoFactorToken`.\n2. Send the `accessToken` you receive on every other request, in the header `Authorization: Bearer `.\n3. The token expires at `exp` (a Unix timestamp in the response). Log in again to get a new one.\n\nA request without a valid token answers `401 NotAuthenticated`. A request for an account you are not a member of answers `403 Forbidden` or `404 NotFound`.\n\n{% securityDefinitions /%}", "version": "1.1.0", "title": "WeShipYou API", "termsOfService": "https://weshipyou.com/legal/terms", "contact": { "name": "API Support", "email": "contact@weshipyou.com", "url": "https://weshipyou.com/docs/api" }, "x-logo": { "url": "https://weshipyou.com/redoc/petstore-logo.png" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } }, "tags": [ { "name": "Authentication", "x-displayName": "Authentication", "description": "Get an access token" }, { "name": "Shipments", "x-displayName": "Shipments", "description": "Create, rate, label, cancel and confirm your shipments" }, { "name": "Tracking", "x-displayName": "Tracking", "description": "Track a package" }, { "name": "Services", "x-displayName": "Services", "description": "WeShipYou services" }, { "name": "Forwarder", "x-displayName": "Forwarder", "description": "Your forwarding orders" }, { "name": "Mobile Recharges", "x-displayName": "Mobile Recharges", "description": "Mobile recharges" }, { "name": "Accounts", "x-displayName": "Accounts", "description": "Your accounts" }, { "name": "Account Addresses", "x-displayName": "Account Addresses", "description": "Your address book" }, { "name": "Transactions", "x-displayName": "Transactions", "description": "Your wallet ledger" }, { "name": "Add Funds", "x-displayName": "Add Funds", "description": "Add money to your wallet" }, { "name": "Add Sub Account", "x-displayName": "Add Sub Account", "description": "Create sub-accounts" } ], "x-tagGroups": [ { "name": "Authentication process", "tags": [ "Authentication" ] }, { "name": "General", "tags": [ "Shipments", "Tracking", "Services" ] }, { "name": "Forwarder", "tags": [ "Forwarder" ] }, { "name": "Mobile Recharges", "tags": [ "Mobile Recharges" ] }, { "name": "Account", "tags": [ "Accounts", "Account Addresses", "Transactions", "Add Funds", "Add Sub Account" ] } ], "paths": { "/authentication": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" } ], "post": { "tags": [ "Authentication" ], "summary": "Get an access token", "description": "Exchanges your username and password (plus the two-factor code when it is on) for a JWT access token. Send it as `Authorization: Bearer ` on every other request.", "operationId": "authentication", "responses": { "201": { "description": "Logged in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" }, "example": { "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImFjY2VzcyJ9.eyJzdWIiOiJjeGZ0b2N2bTJsY2ciLCJhdWQiOiJodHRwczovL3dlc2hpcHlvdS5jb20ifQ.SIGNATURE", "iat": 1793493470, "exp": 1825029470, "user": { "id": 1, "uid": "cxftocvm2lcg", "username": "janedoe", "email": "jane.doe@example.com", "isEnabled": 1, "isVerified": 1, "invalidTokensBeforeAt": null, "metadata": null, "termsAgreementDate": null, "termsAgreementVersion": null, "createdAt": "2026-11-01T00:37:50.000Z", "updatedAt": "2026-11-01T00:37:50.000Z", "deletedAt": null, "roleId": 1, "avatarId": null, "revision": null, "role": { "id": 1, "name": "customer", "inheritPermissionsFromRoleId": null, "inheritPermissionsFromRole": { "id": null, "name": null } }, "avatar": { "id": null, "uid": null, "md5": null, "height": null, "width": null, "format": null, "awsUrl": null }, "user_detail": { "id": null, "uid": null, "taxId": null, "phone": null, "firstName": null, "lastName": null, "displayName": null, "gender": null, "language": null, "birthday": null, "createdAt": null, "updatedAt": null, "deletedAt": null, "userId": null }, "accounts": [ { "name": "Acme Imports", "displayName": "Acme Imports", "systemUnits": "metric", "email": "jane.doe@example.com", "notificationEmail": "jane.doe@example.com", "website": null, "phone": null, "emergencyPhone": null, "taxId": null, "uid": "l96f0r4g37om", "accountNumber": "0000ACC1X1", "status": "active", "language": "en", "isBusiness": 0, "allowBankAccountPayments": 0, "metadata": null, "createdAt": "2026-11-01T00:37:50.000Z", "updatedAt": "2026-11-01T00:37:50.000Z", "deletedAt": null, "addressId": null, "billingAddressId": null, "defaultShipFromId": null, "defaultAddressOnLabelId": null, "defaultReturnAddressId": null, "primaryPaymentShipmentsId": null, "logoId": null, "pickupServiceFallbackId": null, "revision": null, "address": null } ] } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "BadRequest" }, "message": { "type": "string", "example": "Invalid request" }, "code": { "type": "number", "const": 400 }, "className": { "type": "string", "const": "bad-request" }, "data": { "type": "object" } } }, "example": { "name": "BadRequest", "message": "Invalid request", "code": 400, "className": "bad-request", "data": {} } } } }, "401": { "description": "Wrong username or password; `Two-factor authentication required` (with `data.twoFactorRequired: true`) when the code is missing; `Invalid two-factor code` when it is wrong.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Two-factor authentication required" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object", "properties": { "twoFactorRequired": { "type": "boolean" } } } } }, "example": { "name": "NotAuthenticated", "message": "Two-factor authentication required", "code": 401, "className": "not-authenticated", "data": { "twoFactorRequired": true } } } } }, "409": { "description": "`mode: \"test\"` only: the sandbox already has a different user with your username or email.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "Conflict" }, "message": { "type": "string" }, "code": { "type": "number", "const": 409 }, "className": { "type": "string", "const": "conflict" } } }, "example": { "name": "Conflict", "message": "A sandbox user that is not your test-mode mirror already uses this username or email", "code": 409, "className": "conflict" } } } }, "503": { "description": "`mode: \"test\"` only: the sandbox could not be reached or could not open the test session. Your production login is not affected; try again in a minute.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "Unavailable" }, "message": { "type": "string" }, "code": { "type": "number", "const": 503 }, "className": { "type": "string", "const": "unavailable" } } }, "example": { "name": "Unavailable", "message": "The sandbox cannot be reached right now. Try again in a minute.", "code": 503, "className": "unavailable" } } } } }, "security": [], "requestBody": { "$ref": "#/components/requestBodies/Authentication" } } }, "/shipments/rates": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" } ], "post": { "tags": [ "Shipments" ], "summary": "Calculate shipping rates", "description": "Quotes every service available for a shipment. Send the shipment as you would create it; `accountId` is optional. To quote packages that are already in your locker, send each item’s `uid` from `GET /forwarder` as `forwardingOrderItemId` on a parcel item (the *From locker items* example).\n\n**Every rate’s `totalChargePrice` includes insurance (`insuranceFee`), even when you do not ask for it.** If the shipment will not be insured (the default), subtract `insuranceFee` to get the price of its label.", "operationId": "shipmentRates", "responses": { "201": { "description": "The available rates. Each `totalChargePrice` includes insurance (`insuranceFee`); see the Rate object.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Rate" } }, "example": [ { "uid": "k3m9x2p7q1zt", "service": { "uid": "q8c2kd0x1m4z", "name": "USPS Priority Mail", "umbrellaName": "USPS", "serviceType": "ground" }, "totalChargePrice": 20.75, "insuranceFee": 2.35, "improvedFoamProtectionFee": 0, "shipmentChargeTotalPrice": 18.4, "pickupFee": 0, "minimumPickupFee": 0 } ] } } }, "400": { "description": "Invalid parcels, or an unknown `forwardingOrderItemId`", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "BadRequest" }, "message": { "type": "string", "example": "Invalid parcels, or an unknown `forwardingOrderItemId`" }, "code": { "type": "number", "const": 400 }, "className": { "type": "string", "const": "bad-request" }, "data": { "type": "object" } } }, "example": { "name": "BadRequest", "message": "Invalid parcels, or an unknown `forwardingOrderItemId`", "code": 400, "className": "bad-request", "data": {} } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } } }, "requestBody": { "$ref": "#/components/requestBodies/ShipmentRate" } } }, "/shipments": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" } ], "post": { "tags": [ "Shipments" ], "summary": "Add a new shipment to your account", "description": "Creates a shipment (no label yet). `accountId` accepts the account `uid`, its account number (`CU…`) or its external account number. Rate it with `POST /shipments/rates` and buy the label with `POST /shipments/labels`.\n\nTo ship packages that are already in your locker, list them with `GET /forwarder` and send each item’s `uid` as `forwardingOrderItemId` on a parcel item (the *From locker items* example).", "operationId": "addShipment", "responses": { "201": { "description": "The created shipment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentObject" }, "example": { "uid": "42ailx0umn2q", "state": "created", "statusTracking": "in transit", "transactionState": null, "externalReferenceCode": "ORDER-1001", "externalCustomerId": "CUST-42", "externalUniqueId": null, "incoterms": "DDU", "weightUnit": "gm", "dimUnit": "cm", "weight": 2.5, "length": 10, "width": 10, "height": 10, "totalValue": 450, "insurance": true, "insuranceAmount": null, "sellerNotes": null, "buyerNotes": null, "labelCreatedAt": null, "deliveredAt": null, "cancellationReason": null, "cancellationReasonCode": null, "sender": { "uid": "vbnk8892rbji", "nickname": "Main office", "companyName": "We Ship You Corp", "name": "John Doe", "taxId": "88-1345985", "email": "john.doe@weshipyou.com", "phone": "+1 (786) 651-0451", "isResidential": false, "status": "active", "address": { "uid": "e9j57zlvd0z8", "houseNumber": "924", "road": "nw 36 ave", "unit": null, "city": { "name": "Homestead", "state": { "name": "Florida", "isoCode": "FL", "country": { "isoCode": "US", "name": "United States" } } }, "postal_code": { "postalCode": "33033" } } }, "recipient": { "uid": "vbnk8892rbji", "nickname": "Main office", "companyName": "We Ship You Corp", "name": "John Doe", "taxId": "88-1345985", "email": "john.doe@weshipyou.com", "phone": "+1 (786) 651-0451", "isResidential": false, "status": "active", "address": { "uid": "e9j57zlvd0z8", "houseNumber": "924", "road": "nw 36 ave", "unit": null, "city": { "name": "Homestead", "state": { "name": "Florida", "isoCode": "FL", "country": { "isoCode": "US", "name": "United States" } } }, "postal_code": { "postalCode": "33033" } } }, "createdAt": "2026-11-01T00:37:51.000Z", "updatedAt": "2026-11-01T00:37:51.000Z" } } } }, "400": { "description": "Validation error; `data` holds the message for each invalid field", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "BadRequest" }, "message": { "type": "string", "example": "Validation error; `data` holds the message for each invalid field" }, "code": { "type": "number", "const": 400 }, "className": { "type": "string", "const": "bad-request" }, "data": { "type": "object" } } }, "example": { "name": "BadRequest", "message": "Validation error; `data` holds the message for each invalid field", "code": 400, "className": "bad-request", "data": {} } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } }, "403": { "description": "You do not have access to this account", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "Forbidden" }, "message": { "type": "string", "example": "You do not have access to this account" }, "code": { "type": "number", "const": 403 }, "className": { "type": "string", "const": "forbidden" }, "data": { "type": "object" } } }, "example": { "name": "Forbidden", "message": "You do not have access to this account", "code": 403, "className": "forbidden", "data": {} } } } } }, "requestBody": { "$ref": "#/components/requestBodies/Shipment" } }, "get": { "tags": [ "Shipments" ], "summary": "Find shipments", "description": "Lists the shipments of your accounts.", "operationId": "findShipment", "responses": { "200": { "description": "A page of your shipments.", "content": { "application/json": { "schema": { "type": "object", "required": [ "total", "limit", "skip", "data" ], "properties": { "total": { "type": "integer", "description": "Total number of matching records." }, "limit": { "type": "integer", "description": "Page size used for this response." }, "skip": { "type": "integer", "description": "Number of records skipped before this page." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShipmentObject" } } } }, "example": { "total": 1, "limit": 20, "skip": 0, "data": [ { "uid": "wwbvygom0rlz", "state": "created", "statusTracking": "in transit", "transactionState": null, "externalReferenceCode": "shp1x6", "externalCustomerId": null, "externalUniqueId": null, "incoterms": "DDU", "weightUnit": "gm", "dimUnit": "cm", "weight": 1000, "length": 10, "width": 10, "height": 10, "totalValue": 10, "insurance": 0, "insuranceAmount": null, "appliedCouponDiscount": 0, "sellerNotes": null, "buyerNotes": null, "labelCreatedAt": null, "deliveredAt": null, "cancellationReason": null, "cancellationReasonCode": null, "customsAuthorizations": { "required": [], "mincomDocumentsCount": 0, "canCustomerEdit": true, "recipientAuthorization": "optional", "recipientAuthorizationDocumentsCount": 0, "canCustomerEditRecipientAuthorization": true }, "createdAt": "2026-11-01T00:37:50.000Z", "updatedAt": "2026-11-01T00:37:50.000Z" } ] } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } }, "403": { "description": "You do not have access to this account", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "Forbidden" }, "message": { "type": "string", "example": "You do not have access to this account" }, "code": { "type": "number", "const": 403 }, "className": { "type": "string", "const": "forbidden" }, "data": { "type": "object" } } }, "example": { "name": "Forbidden", "message": "You do not have access to this account", "code": 403, "className": "forbidden", "data": {} } } } } }, "parameters": [ { "name": "accountId", "in": "query", "required": false, "description": "Limit the results to one of your accounts or one of their sub-accounts: its `uid`, its account number (`CU…`) or its external account number. Without it, the accounts you belong to and their sub-accounts are all included.", "schema": { "type": "string" } }, { "name": "$limit", "in": "query", "required": false, "description": "Maximum number of results (default 20).", "schema": { "type": "number", "minimum": 0, "maximum": 500, "default": 20 } }, { "name": "$skip", "in": "query", "required": false, "description": "Number of results to skip, for paging.", "schema": { "type": "number", "minimum": 0, "default": 0 } } ] } }, "/shipments/{shipmentId}": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" }, { "name": "shipmentId", "in": "path", "required": true, "description": "The shipment `uid`, or its WeShipYou tracking number (`WSY…`).", "schema": { "type": "string" } } ], "get": { "tags": [ "Shipments" ], "summary": "Get a shipment", "description": "Returns one of your shipments.", "operationId": "getShipment", "responses": { "200": { "description": "The shipment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentObject" }, "example": { "uid": "wwbvygom0rlz", "state": "created", "statusTracking": "in transit", "transactionState": null, "externalReferenceCode": "shp1x6", "externalCustomerId": null, "externalUniqueId": null, "incoterms": "DDU", "weightUnit": "gm", "dimUnit": "cm", "weight": 1000, "length": 10, "width": 10, "height": 10, "totalValue": 10, "insurance": 0, "insuranceAmount": null, "appliedCouponDiscount": 0, "sellerNotes": null, "buyerNotes": null, "labelCreatedAt": null, "deliveredAt": null, "cancellationReason": null, "cancellationReasonCode": null, "customsAuthorizations": { "required": [], "mincomDocumentsCount": 0, "canCustomerEdit": true, "recipientAuthorization": "optional", "recipientAuthorizationDocumentsCount": 0, "canCustomerEditRecipientAuthorization": true }, "createdAt": "2026-11-01T00:37:50.000Z", "updatedAt": "2026-11-01T00:37:50.000Z" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } }, "404": { "description": "No shipment has that id", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotFound" }, "message": { "type": "string", "example": "No record found for id" }, "code": { "type": "number", "const": 404 }, "className": { "type": "string", "const": "not-found" }, "data": { "type": "object" } } }, "example": { "name": "NotFound", "message": "No record found for id", "code": 404, "className": "not-found", "data": {} } } } } } }, "delete": { "tags": [ "Shipments" ], "summary": "Delete a shipment", "description": "Deletes a shipment that has no label yet (state `created`). To cancel a shipment whose label is already bought, use `DELETE /shipments/labels/{trackingNumber}`.", "operationId": "deleteShipment", "responses": { "200": { "description": "The deleted shipment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentObject" }, "example": { "uid": "wwbvygom0rlz", "state": "created", "statusTracking": "in transit", "transactionState": null, "externalReferenceCode": "shp1x6", "externalCustomerId": null, "externalUniqueId": null, "incoterms": "DDU", "weightUnit": "gm", "dimUnit": "cm", "weight": 1000, "length": 10, "width": 10, "height": 10, "totalValue": 10, "insurance": 0, "insuranceAmount": null, "sellerNotes": null, "buyerNotes": null, "labelCreatedAt": null, "deliveredAt": null, "cancellationReason": null, "cancellationReasonCode": null, "createdAt": "2026-11-01T00:37:50.000Z", "updatedAt": "2026-11-01T00:37:50.000Z" } } } }, "400": { "description": "The shipment cannot be deleted in its current state", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "BadRequest" }, "message": { "type": "string", "example": "The shipment cannot be deleted in its current state" }, "code": { "type": "number", "const": 400 }, "className": { "type": "string", "const": "bad-request" }, "data": { "type": "object" } } }, "example": { "name": "BadRequest", "message": "The shipment cannot be deleted in its current state", "code": 400, "className": "bad-request", "data": {} } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } }, "404": { "description": "No shipment has that id", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotFound" }, "message": { "type": "string", "example": "No record found for id" }, "code": { "type": "number", "const": 404 }, "className": { "type": "string", "const": "not-found" }, "data": { "type": "object" } } }, "example": { "name": "NotFound", "message": "No record found for id", "code": 404, "className": "not-found", "data": {} } } } } } }, "patch": { "tags": [ "Shipments" ], "summary": "Update a shipment", "description": "Changes the fields you send and keeps every other field as it is. To change an address, send the whole `sender` or `recipient` object (or `{ \"id\":
, \"useExistingAddress\": true }` to use one from your address book); to change the contents, send the whole `parcels` array. Rates are recalculated after the change. A delivered shipment cannot be edited.", "operationId": "patchShipment", "requestBody": { "description": "Any of the shipment fields.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentPatch" }, "example": { "accountId": "CU1234567", "sender": { "useExistingAddress": false, "nickname": "Main office", "address": { "city": { "name": "Homestead", "state": { "name": "Florida" } }, "street": "924 NW 36 Ave", "postalCode": "33033" }, "name": "John Doe", "companyName": "We Ship You Corp", "taxId": "88-1345985", "taxIdCountry": { "isoCode": "US" }, "phone": "+1 (786) 651-0451", "email": "john.doe@weshipyou.com", "country": { "isoCode": "US" } }, "recipient": { "useExistingAddress": false, "nickname": "Main office", "address": { "city": { "name": "Homestead", "state": { "name": "Florida" } }, "street": "924 NW 36 Ave", "postalCode": "33033" }, "name": "John Doe", "companyName": "We Ship You Corp", "taxId": "88-1345985", "taxIdCountry": { "isoCode": "US" }, "phone": "+1 (786) 651-0451", "email": "john.doe@weshipyou.com", "country": { "isoCode": "US" } }, "totalValue": 2999, "externalReferenceCode": "ORDER-1001", "externalCustomerId": "CUST-42", "insurance": true, "incoterms": "DDU", "parcels": [ { "dimUnit": "cm", "width": 10, "length": 10, "height": 10, "weightUnit": "gm", "weight": 100, "parcel_items": [ { "sku": "SKU-WSY-EXAMPLE", "description": "Play Station 4", "category": { "slug": "board_games" }, "price": 450, "qty": 1, "originCountry": { "isoCode": "JP" }, "weight": 2.5, "currency": "USD" } ] } ] } } } }, "responses": { "200": { "description": "The updated shipment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentObject" }, "example": { "uid": "42ailx0umn2q", "state": "created", "statusTracking": "in transit", "transactionState": null, "externalReferenceCode": "ORDER-1002", "externalCustomerId": "CUST-42", "externalUniqueId": null, "incoterms": "DDU", "weightUnit": "gm", "dimUnit": "cm", "weight": 2.5, "length": 10, "width": 10, "height": 10, "totalValue": 450, "insurance": true, "insuranceAmount": null, "sellerNotes": null, "buyerNotes": null, "labelCreatedAt": null, "deliveredAt": null, "cancellationReason": null, "cancellationReasonCode": null, "sender": { "uid": "vbnk8892rbji", "nickname": "Main office", "companyName": "We Ship You Corp", "name": "John Doe", "taxId": "88-1345985", "email": "john.doe@weshipyou.com", "phone": "+1 (786) 651-0451", "isResidential": false, "status": "active", "address": { "uid": "e9j57zlvd0z8", "houseNumber": "924", "road": "nw 36 ave", "unit": null, "city": { "name": "Homestead", "state": { "name": "Florida", "isoCode": "FL", "country": { "isoCode": "US", "name": "United States" } } }, "postal_code": { "postalCode": "33033" } } }, "recipient": { "uid": "vbnk8892rbji", "nickname": "Main office", "companyName": "We Ship You Corp", "name": "John Doe", "taxId": "88-1345985", "email": "john.doe@weshipyou.com", "phone": "+1 (786) 651-0451", "isResidential": false, "status": "active", "address": { "uid": "e9j57zlvd0z8", "houseNumber": "924", "road": "nw 36 ave", "unit": null, "city": { "name": "Homestead", "state": { "name": "Florida", "isoCode": "FL", "country": { "isoCode": "US", "name": "United States" } } }, "postal_code": { "postalCode": "33033" } } }, "createdAt": "2026-11-01T00:37:51.000Z", "updatedAt": "2026-11-01T00:37:52.000Z" } } } }, "400": { "description": "Validation error, or the shipment can no longer be edited", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "BadRequest" }, "message": { "type": "string", "example": "Validation error, or the shipment can no longer be edited" }, "code": { "type": "number", "const": 400 }, "className": { "type": "string", "const": "bad-request" }, "data": { "type": "object" } } }, "example": { "name": "BadRequest", "message": "Validation error, or the shipment can no longer be edited", "code": 400, "className": "bad-request", "data": {} } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } }, "404": { "description": "No shipment has that id", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotFound" }, "message": { "type": "string", "example": "No record found for id" }, "code": { "type": "number", "const": 404 }, "className": { "type": "string", "const": "not-found" }, "data": { "type": "object" } } }, "example": { "name": "NotFound", "message": "No record found for id", "code": 404, "className": "not-found", "data": {} } } } } } } }, "/shipments/categories": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" } ], "get": { "tags": [ "Shipments" ], "summary": "Get shipment categories", "description": "Lists the content categories a parcel item can declare.", "operationId": "getShipmentCategories", "responses": { "200": { "description": "A page of shipment content categories.", "content": { "application/json": { "schema": { "type": "object", "required": [ "total", "limit", "skip", "data" ], "properties": { "total": { "type": "integer", "description": "Total number of matching records." }, "limit": { "type": "integer", "description": "Page size used for this response." }, "skip": { "type": "integer", "description": "Number of records skipped before this page." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } }, "example": { "total": 30, "limit": 500, "skip": 0, "data": [ { "uid": "u40h56jccmdi", "name": "Phone Accessory (no battery)", "slug": "accessory_no_battery", "weight": null, "length": null, "width": null, "height": null, "containsDocuments": 0, "containsOtherDg": 0, "containsLiquids": 0, "containsBatteryPi967": 0, "containsBatteryPi966": 0, "containsBatteryPi965": 0, "parentId": null } ] } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } }, "403": { "description": "Forbidden" } } } }, "/shipments/country-categories": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" } ], "get": { "tags": [ "Shipments" ], "summary": "Get country categories", "description": "Lists the content categories a destination country uses for customs.", "operationId": "getShipmentCountryCategories", "responses": { "200": { "description": "A page of country-specific content categories.", "content": { "application/json": { "schema": { "type": "object", "required": [ "total", "limit", "skip", "data" ], "properties": { "total": { "type": "integer", "description": "Total number of matching records." }, "limit": { "type": "integer", "description": "Page size used for this response." }, "skip": { "type": "integer", "description": "Number of records skipped before this page." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CountryCategory" } } } }, "example": { "total": 0, "limit": 500, "skip": 0, "data": [] } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } }, "403": { "description": "Forbidden" } } } }, "/services": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" }, { "name": "$limit", "in": "query", "description": "Maximum number of results.", "required": false, "style": "form", "schema": { "type": "number", "minimum": 0, "maximum": 500, "default": 20 } } ], "get": { "tags": [ "Services" ], "summary": "List services", "description": "Lists the shipping services you can rate and buy labels with.", "operationId": "findServices", "responses": { "200": { "description": "A page of services", "content": { "application/json": { "schema": { "type": "object", "required": [ "total", "limit", "skip", "data" ], "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "skip": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } } } }, "example": { "total": 281, "limit": 20, "skip": 0, "data": [ { "uid": "ibrd6l1grbi8", "name": "Allied Express - Road Express", "modality": "standard", "isPickupService": false, "allowPickups": false, "allowDg": false, "supportsMultiRecipient": false, "active": true } ] } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } } } } }, "/forwarder": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" } ], "get": { "tags": [ "Forwarder" ], "summary": "List forwarding orders", "description": "Lists the forwarding orders of your accounts, with their items.", "operationId": "findForwarderOrders", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "skip": { "type": "number" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ForwardingOrder" } } } }, "example": { "total": 1, "limit": 20, "skip": 0, "data": [ { "uid": "0prh3ei97u7b", "wsyOrderNumber": "FOXVIY5BFCPW", "externalReferenceCode": null, "totalPrice": null, "totalItems": 0, "sellerNotes": null, "buyerNotes": null, "personalShopperService": 0, "createdAt": "2026-11-01T00:37:53.000Z", "updatedAt": "2026-11-01T00:37:53.000Z", "destinationCountryId": null, "forwarding_order_items": [ { "uid": "ltinx3lzbjxv", "orderNumber": null, "sku": null, "description": "locker item1xo", "status": "arrived_to_warehouse", "url": null, "qty": 1, "price": null, "shippingCost": 0, "trackingNumber": null, "handlingCost": 1, "weight": 1000, "color": null, "size": null, "alternativeColor": null, "alternativeSize": null, "observations": null, "imageUrl": null, "createdAt": "2026-11-01T00:37:53.000Z", "updatedAt": "2026-11-01T00:37:53.000Z", "currency": {}, "originCountry": {}, "category": { "uid": "u40h56jccmdi", "name": "Phone Accessory (no battery)", "slug": "accessory_no_battery", "weight": null, "length": null, "width": null, "height": null, "containsDocuments": 0, "containsOtherDg": 0, "containsLiquids": 0, "containsBatteryPi967": 0, "containsBatteryPi966": 0, "containsBatteryPi965": 0, "parentId": null }, "country_category": { "uid": null, "name": null, "slug": null, "weight": null, "length": null, "width": null, "height": null, "containsDocuments": null, "containsOtherDg": null, "containsLiquids": null, "containsBatteryPi967": null, "containsBatteryPi966": null, "containsBatteryPi965": null, "customsValue": null, "qty": null, "maxWeight": null, "unitType": null, "observations": null, "isDiscontinued": null, "createdAt": null, "updatedAt": null, "parentId": null } } ] } ] } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } } }, "parameters": [ { "name": "accountId", "in": "query", "required": false, "description": "Limit the results to one of your accounts: its `uid`, its account number (`CU…`) or its external account number. Without it, all the accounts you belong to are included.", "schema": { "type": "string" } }, { "name": "$limit", "in": "query", "required": false, "description": "Maximum number of results (default 20).", "schema": { "type": "number", "minimum": 0, "maximum": 500, "default": 20 } }, { "name": "$skip", "in": "query", "required": false, "description": "Number of results to skip, for paging.", "schema": { "type": "number", "minimum": 0, "default": 0 } } ] } }, "/mobile-recharges/providers": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" }, { "name": "$limit", "in": "query", "description": "Maximum number of results.", "required": false, "style": "form", "schema": { "type": "number", "minimum": 0, "maximum": 500, "default": 20 } } ], "get": { "tags": [ "Mobile Recharges" ], "summary": "List mobile recharge providers", "description": "Lists the mobile operators you can send a recharge to.", "operationId": "findMobileRechargesProviders", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "skip": { "type": "number" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RechargeableProviders" } } } }, "example": { "total": 1, "limit": 20, "skip": 0, "data": [ { "uid": "z4n6xnnf3vtz", "name": "provider1xq", "externalCode": "PRV1XR", "active": 1 } ] } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } } } } }, "/mobile-recharges/providers-descriptions": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" }, { "name": "$limit", "in": "query", "description": "Maximum number of results.", "required": false, "style": "form", "schema": { "type": "number", "minimum": 0, "maximum": 500, "default": 20 } } ], "get": { "tags": [ "Mobile Recharges" ], "summary": "List mobile recharge provider descriptions", "description": "Lists the localized descriptions of the mobile operators.", "operationId": "findMobileRechargesProvidersDescriptions", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "skip": { "type": "number" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RechargeableProvidersDescriptions" } } } }, "example": { "total": 0, "limit": 20, "skip": 0, "data": [] } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } } } } }, "/mobile-recharges/products-descriptions": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" }, { "name": "$limit", "in": "query", "description": "Maximum number of results.", "required": false, "style": "form", "schema": { "type": "number", "minimum": 0, "maximum": 500, "default": 20 } } ], "get": { "tags": [ "Mobile Recharges" ], "summary": "List mobile recharge product descriptions", "description": "Lists the localized descriptions of the recharge products.", "operationId": "findMobileRechargesProductsDescriptions", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "skip": { "type": "number" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RechargeableProductsDescriptions" } } } }, "example": { "total": 0, "limit": 20, "skip": 0, "data": [] } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } } } } }, "/mobile-recharges/recharges": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" }, { "name": "$limit", "in": "query", "description": "Maximum number of results.", "required": false, "style": "form", "schema": { "type": "number", "minimum": 0, "maximum": 500, "default": 20 } } ], "get": { "tags": [ "Mobile Recharges" ], "summary": "List mobile recharges", "description": "Lists the mobile recharges of your accounts.", "operationId": "findMobileRechargesRecharges", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "skip": { "type": "number" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Recharges" } } } }, "example": { "total": 1, "limit": 20, "skip": 0, "data": [ { "uid": "kyzt3evwisxv", "externalReferenceCode": null, "externalCustomerId": null, "status": "awaiting_payment", "amount": 10, "price": 10, "notes": null, "scheduleDate": null, "deliveredAt": null, "countryId": 51, "rechargeableProductId": 1, "rechargeableProviderPromotionId": null, "labelId": null, "couponId": null } ] } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } } } }, "post": { "tags": [ "Mobile Recharges" ], "summary": "Send a mobile recharge", "description": "Orders a top-up for a phone, paid from your wallet balance (or your credit line). The recharge is sent to the operator at once and the response carries its status.", "operationId": "createMobileRechargesRecharges", "x-wsy-charges-wallet": true, "responses": { "201": { "description": "The recharge that was ordered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recharges" }, "example": { "uid": "cb893zbz3h80", "externalReferenceCode": null, "externalCustomerId": null, "status": "delivered", "amount": 10, "price": 11.4, "scheduleDate": null, "deliveredAt": null, "countryId": 51, "rechargeableProductId": 1, "rechargeableProviderPromotionId": null, "labelId": 1, "couponId": null } } } }, "400": { "description": "The body is invalid, or the user cannot buy recharges yet (the account is disabled, the email or the phone number is not verified).", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "BadRequest" }, "message": { "type": "string", "example": "Invalid Request" }, "code": { "type": "number", "const": 400 }, "className": { "type": "string", "const": "bad-request" }, "data": { "type": "object" } } }, "example": { "name": "BadRequest", "message": "Invalid Request", "code": 400, "className": "bad-request" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } } }, "requestBody": { "$ref": "#/components/requestBodies/Recharge" } } }, "/add-funds": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" } ], "post": { "tags": [ "Add Funds" ], "summary": "Add funds to your wallet", "description": "Adds money to your wallet. With `zelle` the payment is registered and credited once WeShipYou confirms it; with `crypto` the paid Coinbase charge is credited at once.", "operationId": "addFunds", "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddFundsResponse" }, "example": { "result": { "account": { "name": "Acme Imports", "displayName": "Acme Imports", "systemUnits": "metric", "email": "jane.doe@example.com", "notificationEmail": "jane.doe@example.com", "website": null, "phone": null, "emergencyPhone": null, "taxId": null, "uid": "un0xo9497f7d", "accountNumber": "000ACC1X12", "status": "active", "language": "en", "isBusiness": false, "allowBankAccountPayments": false, "metadata": null, "createdAt": "2026-11-01T00:37:54.000Z", "updatedAt": "2026-11-01T00:37:54.000Z", "deletedAt": null, "addressId": null, "billingAddressId": null, "defaultShipFromId": null, "defaultAddressOnLabelId": null, "defaultReturnAddressId": null, "primaryPaymentShipmentsId": null, "logoId": null, "pickupServiceFallbackId": null, "revision": 1 } }, "transaction": { "id": 1, "uid": "f3g35lk6rf5vd7550fp31w3ua595nr2l4ce6", "type": "credit", "transType": "Payment", "state": "cleared", "referenceNo": "PNQB9YCJIUS", "description": "Payment from API (add credit) - crypto deposit", "amount": 30, "balance": 30, "accountId": 1, "createdAt": "2026-11-01T00:37:54.652Z", "updatedAt": "2026-11-01T00:37:54.652Z" } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "BadRequest" }, "message": { "type": "string", "example": "Invalid Request" }, "code": { "type": "number", "const": 400 }, "className": { "type": "string", "const": "bad-request" }, "data": { "type": "object" } } }, "example": { "name": "BadRequest", "message": "Invalid Request", "code": 400, "className": "bad-request" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } }, "404": { "description": "The payment was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotFound" }, "message": { "type": "string", "example": "Transaction not found" }, "code": { "type": "number", "const": 404 }, "className": { "type": "string", "const": "not-found" }, "data": { "type": "object" } } }, "example": { "name": "NotFound", "message": "Transaction not found", "code": 404, "className": "not-found" } } } } }, "requestBody": { "$ref": "#/components/requestBodies/AddFunds" } } }, "/add-sub-account": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" } ], "post": { "tags": [ "Add Sub Account" ], "summary": "Add a sub-account", "description": "Creates a sub-account under one of your accounts (`accountUid`), with its own forwarding address. The answer names the parent in `parentUid`; list the sub-accounts later with `GET /accounts?parentUid=`.", "operationId": "addSubAccount", "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSubAccountResponse" }, "example": { "name": "Contract Branch", "displayName": "Contract Branch", "systemUnits": "imperial", "email": "jane.doe@example.com", "notificationEmail": "jane.doe@example.com", "website": "https://example.com", "phone": "+13055550100", "emergencyPhone": "+13055550101", "uid": "85js5f5clt2u", "accountNumber": "CUDHMFEDA9", "parentUid": "h4jupn7wtfqp", "status": "active", "language": "en", "isBusiness": true, "createdAt": "2026-11-01T00:37:55.618Z", "updatedAt": "2026-11-01T00:37:55.618Z", "revision": 1 } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "BadRequest" }, "message": { "type": "string", "example": "Invalid Request" }, "code": { "type": "number", "const": 400 }, "className": { "type": "string", "const": "bad-request" }, "data": { "type": "object" } } }, "example": { "name": "BadRequest", "message": "Invalid Request", "code": 400, "className": "bad-request" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } }, "403": { "description": "`accountUid` is not one of your accounts, or that account may not hold sub-accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "Forbidden" }, "message": { "type": "string", "example": "You can not create a sub-account under this account" }, "code": { "type": "number", "const": 403 }, "className": { "type": "string", "const": "forbidden" }, "data": { "type": "object" } } }, "example": { "name": "Forbidden", "message": "You can not create a sub-account under this account", "code": 403, "className": "forbidden" } } } } }, "requestBody": { "$ref": "#/components/requestBodies/AddSubAccount" } } }, "/shipments/labels": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" } ], "post": { "tags": [ "Shipments" ], "summary": "Buy labels", "description": "Buys the label of one or more shipments at the rate you chose. The charge is booked in your WeShipYou wallet: your balance is used first and only the remainder is charged to `paymentMethod`.\n\nEach label costs its rate’s `totalChargePrice` minus `insuranceFee` when the shipment is not insured (rates always include insurance), plus `pickupFee` and `minimumPickupFee` for a `pickup` handover. A coupon lowers it further.", "operationId": "buyLabels", "x-wsy-charges-wallet": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "handoverOptions" ], "properties": { "accountId": { "type": "string", "description": "Account `uid`, account number (`CU…`) or external account number." }, "paymentMethod": { "description": "How to pay what your wallet balance does not cover: `\"credit_line\"` for accounts with a credit line, or a saved card as `{ \"paymentMethodId\": \"pm_…\" }`. Can be omitted when the balance covers the whole amount.", "oneOf": [ { "type": "string", "enum": [ "credit_line" ] }, { "type": "object", "properties": { "paymentMethodId": { "type": "string" } } } ] }, "usePoints": { "type": "boolean", "description": "Spend your WeShipYou points first." }, "insurance": { "type": "boolean", "description": "Insure every shipment of this purchase (`true`) or none of them (`false`). Leave it out to keep each shipment’s own `insurance`." }, "handoverOptions": { "type": "array", "items": { "type": "object", "required": [ "handoverOption", "shipments" ], "properties": { "handoverOption": { "type": "string", "enum": [ "dropoff", "pickup" ] }, "pickupDate": { "type": "string", "format": "date" }, "pickupTime": { "type": "string" }, "shipments": { "type": "array", "items": { "type": "object", "required": [ "shipmentId", "rateId" ], "properties": { "shipmentId": { "type": "string", "description": "Shipment `uid` or WeShipYou tracking number." }, "rateId": { "type": "string", "description": "The `uid` of the chosen rate of that shipment." } } } } } } } } }, "example": { "accountId": "CU1234567", "paymentMethod": "credit_line", "usePoints": true, "insurance": false, "handoverOptions": [ { "handoverOption": "dropoff", "pickupDate": "2026-10-02", "pickupTime": "10:00", "shipments": [ { "shipmentId": "6f1c2b8e-3d4a-4f5b-9c6d-7e8f9a0b1c2d", "rateId": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e" } ] } ] } } } }, "responses": { "201": { "description": "The outcome of each label batch", "content": { "application/json": { "schema": { "type": "array", "description": "One entry per label batch this request bought. `fulfilled` means every label of the batch was bought; read each shipment (`GET /shipments/{shipmentId}`) for its tracking number.", "items": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "fulfilled", "rejected" ], "description": "Outcome of the batch." }, "reason": { "description": "Why the batch failed, when `status` is `rejected`." } } } }, "example": [ { "status": "fulfilled" } ] } } }, "400": { "description": "Invalid request, payment not found or insufficient funds", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "BadRequest" }, "message": { "type": "string", "example": "Invalid request, payment not found or insufficient funds" }, "code": { "type": "number", "const": 400 }, "className": { "type": "string", "const": "bad-request" }, "data": { "type": "object" } } }, "example": { "name": "BadRequest", "message": "Invalid request, payment not found or insufficient funds", "code": 400, "className": "bad-request", "data": {} } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } }, "403": { "description": "You do not have access to this account", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "Forbidden" }, "message": { "type": "string", "example": "You do not have access to this account" }, "code": { "type": "number", "const": 403 }, "className": { "type": "string", "const": "forbidden" }, "data": { "type": "object" } } }, "example": { "name": "Forbidden", "message": "You do not have access to this account", "code": 403, "className": "forbidden", "data": {} } } } } } } }, "/shipments/labels/{trackingNumber}": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" }, { "name": "trackingNumber", "in": "path", "required": true, "description": "The WeShipYou tracking number of the label.", "schema": { "type": "string" } } ], "delete": { "tags": [ "Shipments" ], "summary": "Cancel a label", "description": "Cancels a label the carrier has not picked up yet. What you paid for it is credited back to your WeShipYou wallet.", "operationId": "cancelLabel", "responses": { "200": { "description": "The label was cancelled", "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "WeShipYou tracking number of the cancelled label." } } }, "example": { "id": "WSYOP5B60J3SCU" } } } }, "400": { "description": "The label can no longer be cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "BadRequest" }, "message": { "type": "string", "example": "The label can no longer be cancelled" }, "code": { "type": "number", "const": 400 }, "className": { "type": "string", "const": "bad-request" }, "data": { "type": "object" } } }, "example": { "name": "BadRequest", "message": "The label can no longer be cancelled", "code": 400, "className": "bad-request", "data": {} } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } }, "403": { "description": "You do not have access to this account", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "Forbidden" }, "message": { "type": "string", "example": "You do not have access to this account" }, "code": { "type": "number", "const": 403 }, "className": { "type": "string", "const": "forbidden" }, "data": { "type": "object" } } }, "example": { "name": "Forbidden", "message": "You do not have access to this account", "code": 403, "className": "forbidden", "data": {} } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotFound" }, "message": { "type": "string", "example": "Not found" }, "code": { "type": "number", "const": 404 }, "className": { "type": "string", "const": "not-found" }, "data": { "type": "object" } } }, "example": { "name": "NotFound", "message": "Not found", "code": 404, "className": "not-found", "data": {} } } } }, "409": { "description": "The shipment changed state while cancelling; retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "Conflict" }, "message": { "type": "string", "example": "The shipment changed state while cancelling; retry" }, "code": { "type": "number", "const": 409 }, "className": { "type": "string", "const": "conflict" }, "data": { "type": "object" } } }, "example": { "name": "Conflict", "message": "The shipment changed state while cancelling; retry", "code": 409, "className": "conflict", "data": {} } } } } } } }, "/shipments/confirm-delivery": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" } ], "post": { "tags": [ "Shipments" ], "summary": "Confirm a delivery", "description": "Records that the recipient received a shipment that is in transit or delivered. No access token is needed: the tracking number and the account number identify the shipment.\n\nA shipment that is already `delivered` can always be confirmed. An `in_transit` shipment can be confirmed only when it is overdue (its label was bought at least 30 days ago and, when it has a delivery promise, at least 15 days have passed since that date) and it has not reached WeShipYou at destination. Once the package is with WeShipYou in Cuba (picked up at the airport or port, on a transit trip or a delivery route), only WeShipYou marks it delivered. A refusal is a 400 with `data.code`: `delivery-confirmation-at-destination`, or `delivery-confirmation-too-early` with `data.availableFrom`.", "operationId": "confirmDelivery", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trackingNumber", "accountNumber" ], "properties": { "trackingNumber": { "type": "string", "example": "WSY0000000000US" }, "accountNumber": { "type": "string", "description": "The account number of the shipment owner (`CU…`)." } } }, "example": { "trackingNumber": "WSY0000000000US", "accountNumber": "CU1234567" } } } }, "responses": { "201": { "description": "Delivery recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "id": { "type": "string", "description": "The tracking number." } } }, "example": { "ok": true, "id": "WSYZD8KI41VSCU" } } } }, "400": { "description": "Missing fields, unknown account or shipment, or a shipment that is not in transit", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "BadRequest" }, "message": { "type": "string", "example": "Missing fields, unknown account or shipment, or a shipment that is not in transit" }, "code": { "type": "number", "const": 400 }, "className": { "type": "string", "const": "bad-request" }, "data": { "type": "object" } } }, "example": { "name": "BadRequest", "message": "Missing fields, unknown account or shipment, or a shipment that is not in transit", "code": 400, "className": "bad-request", "data": {} } } } } } } }, "/tracking/{trackingNumber}": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" }, { "name": "trackingNumber", "in": "path", "required": true, "description": "A WeShipYou tracking number, or the carrier tracking number of the label.", "schema": { "type": "string" } } ], "get": { "tags": [ "Tracking" ], "summary": "Track a package", "description": "Returns the status and the checkpoints of a shipment, parcel or shop order. As the owner you also get the details (addresses, items, locations) that are hidden from other callers.", "operationId": "getTracking", "responses": { "200": { "description": "The tracking", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "trackingNumber": { "type": "string" }, "status": { "type": "string" }, "carrierName": { "type": "string" }, "checkpoints": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "time": { "type": "string", "format": "date-time" }, "location": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "countryIso": { "type": [ "string", "null" ] } } } } } }, "example": { "id": "WSYXAYB4S3NSCU", "trackingNumber": "WSYXAYB4S3NSCU", "status": "created", "carrierName": "Bringer Parcel", "checkpoints": [] } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotFound" }, "message": { "type": "string", "example": "Not found" }, "code": { "type": "number", "const": 404 }, "className": { "type": "string", "const": "not-found" }, "data": { "type": "object" } } }, "example": { "name": "NotFound", "message": "Not found", "code": 404, "className": "not-found", "data": {} } } } } } } }, "/transactions": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" } ], "get": { "tags": [ "Transactions" ], "summary": "List wallet transactions", "description": "Lists the ledger rows of your WeShipYou wallet: payments in, charges for services, refunds and fees.", "operationId": "findTransactions", "parameters": [ { "name": "accountId", "in": "query", "required": false, "description": "Limit the results to one of your accounts: its `uid`, its account number (`CU…`) or its external account number. Without it, all the accounts you belong to are included.", "schema": { "type": "string" } }, { "name": "$limit", "in": "query", "required": false, "description": "Maximum number of results (default 20).", "schema": { "type": "number", "minimum": 0, "maximum": 500, "default": 20 } }, { "name": "$skip", "in": "query", "required": false, "description": "Number of results to skip, for paging.", "schema": { "type": "number", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "A page of transactions", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "skip": { "type": "number" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } } } }, "example": { "total": 1, "limit": 20, "skip": 0, "data": [ { "id": 1, "uid": "3s91olwt4rs47np8cctft3pmgiwoy7hvnw01", "type": "credit", "transType": "Payment", "state": "cleared", "referenceNo": "P2Y2P8XAEUS", "description": "Card payment received (test stripe pi_test_p2y2p8xaeus)", "courierName": null, "amount": 25, "balance": 25, "accountId": 1, "adjustmentTypeId": null, "createdAt": "2026-11-01T00:37:54.000Z", "updatedAt": "2026-11-01T00:37:54.000Z" } ] } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } }, "403": { "description": "You do not have access to this account", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "Forbidden" }, "message": { "type": "string", "example": "You do not have access to this account" }, "code": { "type": "number", "const": 403 }, "className": { "type": "string", "const": "forbidden" }, "data": { "type": "object" } } }, "example": { "name": "Forbidden", "message": "You do not have access to this account", "code": 403, "className": "forbidden", "data": {} } } } } } } }, "/transactions/{transactionId}": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" }, { "name": "transactionId", "in": "path", "required": true, "description": "The transaction `uid`.", "schema": { "type": "string" } } ], "get": { "tags": [ "Transactions" ], "summary": "Get a wallet transaction", "description": "Returns one ledger row of your wallet.", "operationId": "getTransaction", "responses": { "200": { "description": "The transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "example": { "id": 1, "uid": "3s91olwt4rs47np8cctft3pmgiwoy7hvnw01", "type": "credit", "transType": "Payment", "state": "cleared", "referenceNo": "P2Y2P8XAEUS", "description": "Card payment received (test stripe pi_test_p2y2p8xaeus)", "courierName": null, "amount": 25, "balance": 25, "accountId": 1, "adjustmentTypeId": null, "createdAt": "2026-11-01T00:37:54.000Z", "updatedAt": "2026-11-01T00:37:54.000Z" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } }, "404": { "description": "No shipment has that id", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotFound" }, "message": { "type": "string", "example": "No record found for id" }, "code": { "type": "number", "const": 404 }, "className": { "type": "string", "const": "not-found" }, "data": { "type": "object" } } }, "example": { "name": "NotFound", "message": "No record found for id", "code": 404, "className": "not-found", "data": {} } } } } } } }, "/forwarder/{forwardingOrderId}": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" }, { "name": "forwardingOrderId", "in": "path", "required": true, "description": "The forwarding order `uid`.", "schema": { "type": "string" } } ], "get": { "tags": [ "Forwarder" ], "summary": "Get a forwarding order", "description": "Returns one of your forwarding orders with its items.", "operationId": "getForwarderOrder", "responses": { "200": { "description": "The forwarding order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardingOrder" }, "example": { "uid": "0prh3ei97u7b", "wsyOrderNumber": "FOXVIY5BFCPW", "externalReferenceCode": null, "totalPrice": null, "totalItems": 0, "sellerNotes": null, "buyerNotes": null, "personalShopperService": 0, "createdAt": "2026-11-01T00:37:53.000Z", "updatedAt": "2026-11-01T00:37:53.000Z", "destinationCountryId": null, "forwarding_order_items": [ { "uid": "ltinx3lzbjxv", "orderNumber": null, "sku": null, "description": "locker item1xo", "status": "arrived_to_warehouse", "url": null, "qty": 1, "price": null, "shippingCost": 0, "trackingNumber": null, "handlingCost": 1, "weight": 1000, "color": null, "size": null, "alternativeColor": null, "alternativeSize": null, "observations": null, "imageUrl": null, "createdAt": "2026-11-01T00:37:53.000Z", "updatedAt": "2026-11-01T00:37:53.000Z", "currency": {}, "originCountry": {}, "category": { "uid": "u40h56jccmdi", "name": "Phone Accessory (no battery)", "slug": "accessory_no_battery", "weight": null, "length": null, "width": null, "height": null, "containsDocuments": 0, "containsOtherDg": 0, "containsLiquids": 0, "containsBatteryPi967": 0, "containsBatteryPi966": 0, "containsBatteryPi965": 0, "parentId": null }, "country_category": { "uid": null, "name": null, "slug": null, "weight": null, "length": null, "width": null, "height": null, "containsDocuments": null, "containsOtherDg": null, "containsLiquids": null, "containsBatteryPi967": null, "containsBatteryPi966": null, "containsBatteryPi965": null, "customsValue": null, "qty": null, "maxWeight": null, "unitType": null, "observations": null, "isDiscontinued": null, "createdAt": null, "updatedAt": null, "parentId": null } } ] } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } }, "404": { "description": "No shipment has that id", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotFound" }, "message": { "type": "string", "example": "No record found for id" }, "code": { "type": "number", "const": 404 }, "className": { "type": "string", "const": "not-found" }, "data": { "type": "object" } } }, "example": { "name": "NotFound", "message": "No record found for id", "code": 404, "className": "not-found", "data": {} } } } } } } }, "/accounts": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" } ], "get": { "tags": [ "Accounts" ], "summary": "List your accounts", "description": "Lists the accounts you belong to and their sub-accounts. Each account names its parent in `parentUid` (`null` on an account you belong to directly), so `?parentUid=` lists the sub-accounts of one account.", "operationId": "findAccounts", "parameters": [ { "name": "$limit", "in": "query", "required": false, "description": "Maximum number of results (default 20).", "schema": { "type": "number", "minimum": 0, "maximum": 500, "default": 20 } }, { "name": "$skip", "in": "query", "required": false, "description": "Number of results to skip, for paging.", "schema": { "type": "number", "minimum": 0, "default": 0 } }, { "name": "parentUid", "in": "query", "required": false, "description": "Only the sub-accounts of this account: its `uid`, its account number (`CU…`) or its external account number. An account you cannot access returns an empty list.", "schema": { "type": "string" }, "example": "h4jupn7wtfqp" } ], "responses": { "200": { "description": "A page of accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "skip": { "type": "number" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } } } }, "example": { "total": 2, "limit": 20, "skip": 0, "data": [ { "name": "Acme Imports", "displayName": "Acme Imports", "systemUnits": "metric", "email": "jane.doe@example.com", "notificationEmail": "jane.doe@example.com", "website": null, "phone": null, "emergencyPhone": null, "taxId": null, "uid": "h4jupn7wtfqp", "accountNumber": "000ACC1X16", "parentUid": null, "status": "active", "language": "en", "isBusiness": 0, "createdAt": "2026-11-01T00:37:55.000Z", "updatedAt": "2026-11-01T00:37:55.000Z", "deletedAt": null, "addressId": null, "billingAddressId": null, "defaultShipFromId": null, "defaultAddressOnLabelId": null, "defaultReturnAddressId": null, "primaryPaymentShipmentsId": null, "pickupServiceFallbackId": null, "revision": null }, { "name": "Acme Imports Orlando", "displayName": "Acme Imports Orlando", "systemUnits": "imperial", "email": "orlando@example.com", "notificationEmail": "orlando@example.com", "website": null, "phone": "+13055550100", "emergencyPhone": "+13055550101", "taxId": null, "uid": "85js5f5clt2u", "accountNumber": "CUDHMFEDA9", "parentUid": "h4jupn7wtfqp", "status": "active", "language": "en", "isBusiness": 1, "createdAt": "2026-11-01T00:40:12.000Z", "updatedAt": "2026-11-01T00:40:12.000Z", "deletedAt": null, "addressId": null, "billingAddressId": null, "defaultShipFromId": null, "defaultAddressOnLabelId": null, "defaultReturnAddressId": null, "primaryPaymentShipmentsId": null, "pickupServiceFallbackId": null, "revision": 1 } ] } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } } } } }, "/accounts/{accountId}": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" }, { "name": "accountId", "in": "path", "required": true, "description": "Account `uid`, account number (`CU…`) or external account number, of an account you belong to or one of its sub-accounts.", "schema": { "type": "string" } } ], "get": { "tags": [ "Accounts" ], "summary": "Get an account", "operationId": "getAccount", "responses": { "200": { "description": "The account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "example": { "name": "Acme Imports", "displayName": "Acme Imports", "systemUnits": "metric", "email": "jane.doe@example.com", "notificationEmail": "jane.doe@example.com", "website": null, "phone": null, "emergencyPhone": null, "taxId": null, "uid": "h4jupn7wtfqp", "accountNumber": "000ACC1X16", "parentUid": null, "status": "active", "language": "en", "isBusiness": 0, "createdAt": "2026-11-01T00:37:55.000Z", "updatedAt": "2026-11-01T00:37:55.000Z", "deletedAt": null, "addressId": null, "billingAddressId": null, "defaultShipFromId": null, "defaultAddressOnLabelId": null, "defaultReturnAddressId": null, "primaryPaymentShipmentsId": null, "pickupServiceFallbackId": null, "revision": null } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } }, "404": { "description": "No shipment has that id", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotFound" }, "message": { "type": "string", "example": "No record found for id" }, "code": { "type": "number", "const": 404 }, "className": { "type": "string", "const": "not-found" }, "data": { "type": "object" } } }, "example": { "name": "NotFound", "message": "No record found for id", "code": 404, "className": "not-found", "data": {} } } } } } }, "patch": { "tags": [ "Accounts" ], "summary": "Update an account", "description": "Changes the profile fields you send (name, contact details, language, units).", "operationId": "patchAccount", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountPatch" }, "example": { "displayName": "Jane's Store", "notificationEmail": "orders@janesstore.com", "phone": "+1 (786) 651-0451" } } } }, "responses": { "200": { "description": "The updated account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "example": { "name": "Acme Imports", "displayName": "Contract Store", "systemUnits": "metric", "email": "jane.doe@example.com", "notificationEmail": "jane.doe@example.com", "website": null, "phone": null, "emergencyPhone": null, "taxId": null, "uid": "h4jupn7wtfqp", "accountNumber": "000ACC1X16", "parentUid": null, "status": "active", "language": "en", "isBusiness": 0, "allowBankAccountPayments": 0, "metadata": { "ip": "127.0.0.1", "method": "patch", "path": "v1/accounts", "userId": 1, "editedVia": "rest", "serviceProvider": "rest", "date": "2026-11-01T00:37:55.396Z" }, "createdAt": "2026-11-01T00:37:55.000Z", "updatedAt": "2026-11-01T00:37:55.000Z", "deletedAt": null, "addressId": null, "billingAddressId": null, "defaultShipFromId": null, "defaultAddressOnLabelId": null, "defaultReturnAddressId": null, "primaryPaymentShipmentsId": null, "logoId": null, "pickupServiceFallbackId": null, "revision": 1 } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "BadRequest" }, "message": { "type": "string", "example": "Invalid request" }, "code": { "type": "number", "const": 400 }, "className": { "type": "string", "const": "bad-request" }, "data": { "type": "object" } } }, "example": { "name": "BadRequest", "message": "Invalid request", "code": 400, "className": "bad-request", "data": {} } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } }, "403": { "description": "You do not have access to this account", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "Forbidden" }, "message": { "type": "string", "example": "You do not have access to this account" }, "code": { "type": "number", "const": 403 }, "className": { "type": "string", "const": "forbidden" }, "data": { "type": "object" } } }, "example": { "name": "Forbidden", "message": "You do not have access to this account", "code": 403, "className": "forbidden", "data": {} } } } }, "404": { "description": "No shipment has that id", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotFound" }, "message": { "type": "string", "example": "No record found for id" }, "code": { "type": "number", "const": 404 }, "className": { "type": "string", "const": "not-found" }, "data": { "type": "object" } } }, "example": { "name": "NotFound", "message": "No record found for id", "code": 404, "className": "not-found", "data": {} } } } } } } }, "/account-addresses": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" } ], "get": { "tags": [ "Account Addresses" ], "summary": "List your address book", "description": "Lists the saved senders and recipients of your accounts.", "operationId": "findAccountAddresses", "parameters": [ { "name": "accountId", "in": "query", "required": false, "description": "Limit the results to one of your accounts: its `uid`, its account number (`CU…`) or its external account number. Without it, all the accounts you belong to are included.", "schema": { "type": "string" } }, { "name": "$limit", "in": "query", "required": false, "description": "Maximum number of results (default 20).", "schema": { "type": "number", "minimum": 0, "maximum": 500, "default": 20 } }, { "name": "$skip", "in": "query", "required": false, "description": "Number of results to skip, for paging.", "schema": { "type": "number", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "A page of your saved addresses.", "content": { "application/json": { "schema": { "type": "object", "required": [ "total", "limit", "skip", "data" ], "properties": { "total": { "type": "integer", "description": "Total number of matching records." }, "limit": { "type": "integer", "description": "Page size used for this response." }, "skip": { "type": "integer", "description": "Number of records skipped before this page." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccountAddressObject" } } } }, "example": { "total": 1, "limit": 20, "skip": 0, "data": [ { "uid": "3cl95vgkut4n", "nickname": null, "name": null, "companyName": null, "taxId": null, "email": null, "phone": null, "birthday": null, "isRecipient": 0, "isSender": 0, "isResidential": 0, "status": "active", "createdAt": "2026-11-01T00:37:55.000Z", "updatedAt": "2026-11-01T00:37:55.000Z" } ] } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } }, "403": { "description": "You do not have access to this account", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "Forbidden" }, "message": { "type": "string", "example": "You do not have access to this account" }, "code": { "type": "number", "const": 403 }, "className": { "type": "string", "const": "forbidden" }, "data": { "type": "object" } } }, "example": { "name": "Forbidden", "message": "You do not have access to this account", "code": 403, "className": "forbidden", "data": {} } } } } } }, "post": { "tags": [ "Account Addresses" ], "summary": "Save an address", "description": "Adds a sender or recipient to the address book of one of your accounts (`accountId`).", "operationId": "createAccountAddress", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/AccountAddress" }, { "type": "object", "required": [ "accountId" ], "properties": { "accountId": { "type": "string" } } } ], "unevaluatedProperties": false }, "example": { "useExistingAddress": true, "nickname": "Main office", "address": { "city": { "name": "Homestead", "state": { "name": "Florida" } }, "street": "924 NW 36 Ave", "postalCode": "33033" }, "name": "John Doe", "companyName": "We Ship You Corp", "taxId": "88-1345985", "taxIdCountry": { "isoCode": "US" }, "phone": "+1 (786) 651-0451", "email": "john.doe@weshipyou.com", "country": { "isoCode": "US" }, "accountId": "CU1234567" } } } }, "responses": { "201": { "description": "The saved address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountAddressObject" }, "example": { "uid": "a3neeyyhaytn", "nickname": "Warehouse", "name": "Jane Doe", "companyName": null, "email": "jane.doe@example.com", "phone": "+1 (305) 555-0100", "birthday": null, "isRecipient": false, "isSender": false, "isResidential": false, "status": "active", "createdAt": "2026-11-01T00:37:55.921Z", "updatedAt": "2026-11-01T00:37:55.921Z" } } } }, "400": { "description": "Validation error; `data` holds the message for each invalid field", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "BadRequest" }, "message": { "type": "string", "example": "Validation error; `data` holds the message for each invalid field" }, "code": { "type": "number", "const": 400 }, "className": { "type": "string", "const": "bad-request" }, "data": { "type": "object" } } }, "example": { "name": "BadRequest", "message": "Validation error; `data` holds the message for each invalid field", "code": 400, "className": "bad-request", "data": {} } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } }, "403": { "description": "You do not have access to this account", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "Forbidden" }, "message": { "type": "string", "example": "You do not have access to this account" }, "code": { "type": "number", "const": 403 }, "className": { "type": "string", "const": "forbidden" }, "data": { "type": "object" } } }, "example": { "name": "Forbidden", "message": "You do not have access to this account", "code": 403, "className": "forbidden", "data": {} } } } } } } }, "/account-addresses/{accountAddressId}": { "parameters": [ { "$ref": "#/components/parameters/Accept-Language" }, { "name": "accountAddressId", "in": "path", "required": true, "description": "The address `uid`.", "schema": { "type": "string" } } ], "patch": { "tags": [ "Account Addresses" ], "summary": "Update an address", "description": "Changes the fields you send. While the address is used by a shipment that is in transit or delivered, its identity fields (name, phone, address, tax id, …) cannot change and the request answers 400; save a new address instead.", "operationId": "patchAccountAddress", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountAddress" }, "example": { "useExistingAddress": true, "nickname": "Main office", "address": { "city": { "name": "Homestead", "state": { "name": "Florida" } }, "street": "924 NW 36 Ave", "postalCode": "33033" }, "name": "John Doe", "companyName": "We Ship You Corp", "taxId": "88-1345985", "taxIdCountry": { "isoCode": "US" }, "phone": "+1 (786) 651-0451", "email": "john.doe@weshipyou.com", "country": { "isoCode": "US" } } } } }, "responses": { "200": { "description": "The updated address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountAddressObject" }, "example": { "uid": "3cl95vgkut4n", "nickname": "Office", "name": null, "companyName": null, "taxId": null, "email": null, "phone": null, "birthday": null, "isRecipient": 0, "isSender": 0, "isResidential": 0, "status": "active", "createdAt": "2026-11-01T00:37:55.000Z", "updatedAt": "2026-11-01T00:37:55.000Z" } } } }, "400": { "description": "Validation error, or a locked field of an address in use", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "BadRequest" }, "message": { "type": "string", "example": "Validation error, or a locked field of an address in use" }, "code": { "type": "number", "const": 400 }, "className": { "type": "string", "const": "bad-request" }, "data": { "type": "object" } } }, "example": { "name": "BadRequest", "message": "Validation error, or a locked field of an address in use", "code": 400, "className": "bad-request", "data": {} } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotAuthenticated" }, "message": { "type": "string", "example": "Missing or invalid access token" }, "code": { "type": "number", "const": 401 }, "className": { "type": "string", "const": "not-authenticated" }, "data": { "type": "object" } } }, "example": { "name": "NotAuthenticated", "message": "Missing or invalid access token", "code": 401, "className": "not-authenticated", "data": {} } } } }, "403": { "description": "You do not have access to this account", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "Forbidden" }, "message": { "type": "string", "example": "You do not have access to this account" }, "code": { "type": "number", "const": 403 }, "className": { "type": "string", "const": "forbidden" }, "data": { "type": "object" } } }, "example": { "name": "Forbidden", "message": "You do not have access to this account", "code": 403, "className": "forbidden", "data": {} } } } }, "404": { "description": "No shipment has that id", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "NotFound" }, "message": { "type": "string", "example": "No record found for id" }, "code": { "type": "number", "const": 404 }, "className": { "type": "string", "const": "not-found" }, "data": { "type": "object" } } }, "example": { "name": "NotFound", "message": "No record found for id", "code": 404, "className": "not-found", "data": {} } } } } } } } }, "components": { "schemas": { "CountryProperty": { "type": "object", "description": "A country, by its ISO 3166-1 alpha-2 code.", "properties": { "isoCode": { "type": "string", "minLength": 2, "maxLength": 2, "example": "US", "enum": [ "AD", "AE", "AF", "AL", "AG", "AI", "AQ", "AM", "AO", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "XK", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "HU", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SS", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YT", "YE", "ZA", "ZM", "ZW", "CS", "AN" ] } } }, "AuthResponse": { "title": "Access token", "type": "object", "properties": { "accessToken": { "type": "string" }, "iat": { "type": "number" }, "exp": { "type": "number" }, "user": { "$ref": "#/components/schemas/User" } } }, "AddFundsResponse": { "title": "Funds request", "type": "object", "description": "The wallet credit that was booked. Depending on the payment method the account is returned under `result.account` or `account`; a request that only registers a pending payment answers `{ \"ok\": true }`.", "properties": { "ok": { "const": true, "description": "The payment was registered and will be credited once it is confirmed." }, "result": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Account", "description": "The account after the credit." } } }, "account": { "$ref": "#/components/schemas/Account", "description": "The account after the credit." }, "transaction": { "$ref": "#/components/schemas/Transaction", "description": "The wallet credit." }, "transactionFee": { "$ref": "#/components/schemas/Transaction", "description": "The processing fee charged for the payment, when there is one." } } }, "AddSubAccountResponse": { "title": "Sub-account", "type": "object", "$ref": "#/components/schemas/Account" }, "User": { "type": "object", "properties": { "id": { "type": "number" }, "uid": { "type": "string" }, "username": { "type": "string" }, "email": { "type": "string" }, "isEnabled": { "type": [ "boolean", "integer" ] }, "isVerified": { "type": [ "boolean", "integer" ] }, "invalidTokensBeforeAt": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": [ "object", "null" ] }, "termsAgreementDate": { "type": [ "string", "null" ], "format": "date-time" }, "termsAgreementVersion": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time" }, "roleId": { "type": "number" }, "avatarId": { "type": [ "number", "null" ] }, "revision": { "type": [ "number", "null" ] }, "role": { "type": "object" }, "avatar": { "type": "object" }, "user_detail": { "type": "object", "properties": { "id": { "type": [ "number", "null" ] }, "uid": { "type": [ "string", "null" ] }, "taxId": { "type": [ "string", "null" ], "example": "88-1345985" }, "phone": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] }, "gender": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "birthday": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time" }, "userId": { "type": [ "number", "null" ] } } }, "accounts": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/Account" } } } }, "AccountAddress": { "type": "object", "required": [ "name", "email", "phone", "address", "country" ], "discriminator": { "propertyName": "country", "mapping": { "brazil": "#/components/schemas/CountryBrazil", "cuba": "#/components/schemas/CountryCuba", "colombia": "#/components/schemas/CountryColombia" } }, "properties": { "useExistingAddress": { "type": "boolean" }, "nickname": { "type": [ "string", "null" ] }, "address": { "type": "object", "properties": { "city": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "minLength": 0, "example": "Homestead" }, "state": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "minLength": 0, "example": "Florida" } } } } }, "street": { "description": "Street address, including the building or apartment number.", "type": "string", "minLength": 0, "example": "924 NW 36 Ave" }, "postalCode": { "type": "string", "example": "33033" } } }, "name": { "type": [ "string", "null" ], "minLength": 1, "example": "John Doe" }, "companyName": { "type": [ "string", "null" ], "example": "We Ship You Corp" }, "taxId": { "type": [ "string", "null" ], "example": "88-1345985" }, "taxIdCountry": { "$ref": "#/components/schemas/CountryProperty" }, "phone": { "type": [ "string", "null" ], "minLength": 1, "format": "phone", "example": "+1 (786) 651-0451" }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Recipient email address", "example": "john.doe@weshipyou.com" }, "country": { "$ref": "#/components/schemas/CountryProperty" } } }, "RatesAddress": { "additionalProperties": false, "type": "object", "required": [ "address", "country" ], "discriminator": { "propertyName": "country", "mapping": { "brazil": "#/components/schemas/CountryBrazil", "cuba": "#/components/schemas/CountryCuba", "colombia": "#/components/schemas/CountryColombia" } }, "properties": { "address": { "type": "object", "properties": { "city": { "type": "object", "properties": { "name": { "type": "string", "minLength": 0, "example": "Homestead" }, "state": { "type": "object", "properties": { "name": { "type": "string", "minLength": 0, "example": "Florida" } } } } }, "street": { "description": "Street address, including the building or apartment number.", "type": "string", "minLength": 0, "example": "924 NW 36 Ave" }, "postalCode": { "type": "string", "example": "33033" } } }, "country": { "$ref": "#/components/schemas/CountryProperty" } } }, "Currency": { "type": "object", "required": [ "name", "code", "prefix" ], "properties": { "name": { "type": "string" }, "code": { "type": "string" }, "prefix": { "type": "string" } } }, "CountryCategory": { "title": "Country category", "type": "object", "properties": { "uid": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "weight": { "type": [ "number", "null" ] }, "length": { "type": [ "number", "null" ] }, "width": { "type": [ "number", "null" ] }, "height": { "type": [ "number", "null" ] }, "containsDocuments": { "type": [ "boolean", "null" ] }, "containsOtherDg": { "type": [ "boolean", "null" ] }, "containsLiquids": { "type": [ "boolean", "null" ] }, "containsBatteryPi967": { "type": [ "boolean", "null" ] }, "containsBatteryPi966": { "type": [ "boolean", "null" ] }, "containsBatteryPi965": { "type": [ "boolean", "null" ] }, "customsValue": { "type": [ "number", "null" ] }, "qty": { "type": [ "number", "null" ] }, "maxWeight": { "type": [ "number", "null" ] }, "unitType": { "type": [ "string", "null" ] }, "observations": { "type": [ "string", "null" ] }, "isDiscontinued": { "type": [ "boolean", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "parentId": { "type": [ "number", "null" ] } } }, "ForwardingOrderItem": { "type": "object", "properties": { "uid": { "type": "string" }, "orderNumber": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "status": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "qty": { "type": "number" }, "price": { "type": [ "number", "null" ] }, "shippingCost": { "type": "number" }, "trackingNumber": { "type": [ "string", "null" ] }, "handlingCost": { "type": "number" }, "weight": { "type": "number" }, "color": { "type": [ "string", "null" ] }, "size": { "type": [ "string", "null" ] }, "alternativeColor": { "type": [ "string", "null" ] }, "alternativeSize": { "type": [ "string", "null" ] }, "observations": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "currency": { "type": "object", "properties": {} }, "originCountry": { "type": "object", "properties": {} }, "category": { "$ref": "#/components/schemas/Category" }, "country_category": { "$ref": "#/components/schemas/CountryCategory" } } }, "ForwardingOrder": { "title": "Forwarding order", "type": "object", "required": [], "properties": { "uid": { "type": "string", "example": "vd7x0pekjjz5" }, "wsyOrderNumber": { "type": "string", "example": "WFO-7EB7DU" }, "externalReferenceCode": { "type": [ "string", "null" ] }, "totalPrice": { "type": [ "number", "null" ] }, "totalItems": { "type": "number" }, "sellerNotes": { "type": [ "string", "null" ] }, "buyerNotes": { "type": [ "string", "null" ] }, "personalShopperService": { "type": [ "boolean", "integer" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "destinationCountryId": { "type": [ "integer", "null" ], "description": "Id of the destination country (see `GET /shipments/country-categories`).", "example": 52 }, "forwarding_order_items": { "type": "array", "items": { "$ref": "#/components/schemas/ForwardingOrderItem" } } } }, "RechargeableProviders": { "title": "Recharge provider", "type": "object", "required": [], "properties": { "uid": { "type": "string", "example": "vd7x0pekjjz5" }, "name": { "type": "string", "example": "Cubacel" }, "externalCode": { "type": "string", "example": "CUCU" }, "active": { "type": [ "boolean", "integer" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "RechargeableProvidersDescriptions": { "title": "Provider description", "type": "object", "required": [], "properties": { "uid": { "type": "string", "example": "vd7x0pekjjz5" }, "displayName": { "type": "string", "example": "Cubacel" }, "description": { "type": "string" }, "localeId": { "type": "number" }, "providerId": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "RechargeableProductsDescriptions": { "title": "Product description", "type": "object", "required": [], "properties": { "uid": { "type": "string", "example": "vd7x0pekjjz5" }, "title": { "type": "string", "example": "EUR 10.00" }, "descriptionMarkdown": { "type": "string" }, "extendedDescriptionMarkdown": { "type": "string" }, "localizationKey": { "type": "string", "example": "0ALULU96671" }, "productId": { "type": "number" }, "localeId": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Recharges": { "title": "Recharge", "type": "object", "required": [], "properties": { "uid": { "type": "string", "example": "vd7x0pekjjz5" }, "externalReferenceCode": { "type": [ "string", "null" ] }, "externalCustomerId": { "type": [ "string", "null" ] }, "status": { "type": "string", "example": "delivered" }, "amount": { "type": "number" }, "price": { "type": "number" }, "notes": { "type": [ "string", "null" ] }, "scheduleDate": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "accountId": { "type": "number" }, "countryId": { "type": "number" }, "rechargeableProductId": { "type": "number" }, "rechargeableProviderPromotionId": { "type": [ "number", "null" ] }, "labelId": { "type": [ "number", "null" ] }, "couponId": { "type": [ "number", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Parcel": { "type": "object", "required": [ "dimUnit", "width", "length", "height", "weightUnit", "weight", "parcel_items" ], "properties": { "dimUnit": { "type": "string", "enum": [ "cm", "in" ], "description": "Unit of `length`, `width` and `height`." }, "width": { "type": "number", "example": 10 }, "length": { "type": "number", "example": 10 }, "height": { "type": "number", "example": 10 }, "weightUnit": { "type": "string", "default": "gm", "description": "Unit of `weight`.", "example": "gm", "enum": [ "gm", "kg", "oz", "lb" ] }, "weight": { "type": "number", "minimum": 0.01, "example": 100 }, "parcel_items": { "$ref": "#/components/schemas/parcel_items" } } }, "ParcelItem": { "type": "object", "required": [ "qty", "price", "description", "currency", "category" ], "properties": { "sku": { "type": "string", "example": "SKU-WSY-EXAMPLE" }, "forwardingOrderItemId": { "type": "string", "description": "Ships a package that is already in your locker: the `uid` of the forwarding order item, as listed by `GET /forwarder`. The item must belong to the shipment’s account. Its weight and quantity, and its declared value when it has one, are read from the locker, and the parcel’s dimensions are recalculated from its weight. An unknown `uid`, or an item of another account, is a 400.", "example": "ltinx3lzbjxv" }, "description": { "type": "string", "minLength": 1, "example": "Play Station 4" }, "category": { "required": [ "slug" ], "type": "object", "properties": { "slug": { "type": "string", "example": "board_games" } } }, "price": { "type": "number", "example": 450 }, "qty": { "type": "number", "example": 1 }, "originCountry": { "type": "object", "properties": { "isoCode": { "type": "string", "minLength": 2, "example": "JP" } } }, "weight": { "type": "number" }, "currency": { "description": "Currency of the item value: an ISO 4217 code, or a currency object.", "oneOf": [ { "type": "string", "example": "USD" }, { "$ref": "#/components/schemas/Currency" } ], "example": "USD" } } }, "sender": { "type": "object", "required": [ "useExistingAddress" ], "properties": { "useExistingAddress": { "type": "boolean" } }, "if": { "type": "object", "title": "New address", "required": [ "useExistingAddress" ], "properties": { "useExistingAddress": { "type": "boolean", "const": false } } }, "then": { "allOf": [ { "$ref": "#/components/schemas/AccountAddress" }, { "properties": { "useExistingAddress": { "type": "boolean", "const": false } } } ] }, "else": { "title": "Using existing address", "additionalProperties": false, "type": "object", "required": [ "address" ], "properties": { "useExistingAddress": { "type": "boolean" }, "address": { "type": "object", "properties": { "id": { "description": "Address ID", "$ref": "#/components/schemas/IdReadable" } } } } } }, "recipient": { "type": "object", "required": [ "useExistingAddress" ], "properties": { "useExistingAddress": { "type": "boolean" } }, "if": { "type": "object", "required": [ "useExistingAddress" ], "properties": { "useExistingAddress": { "type": "boolean", "const": false } } }, "then": { "allOf": [ { "$ref": "#/components/schemas/AccountAddress" }, { "properties": { "useExistingAddress": { "type": "boolean", "const": false } } } ] }, "else": { "additionalProperties": false, "required": [ "address" ], "properties": { "useExistingAddress": { "type": "boolean" }, "address": { "type": "object", "properties": { "id": { "description": "Address ID", "$ref": "#/components/schemas/IdReadable" } } } } } }, "formStep1": { "type": "object", "properties": { "sender": { "$ref": "#/components/schemas/sender" }, "recipient": { "$ref": "#/components/schemas/recipient" } } }, "formStep2": { "allOf": [ { "$ref": "#/components/schemas/formStep1" }, { "type": "object", "required": [ "parcels", "sender", "recipient", "totalValue", "incoterms" ], "properties": { "totalValue": { "type": "number", "maximum": 2999 }, "externalReferenceCode": { "type": "string" }, "externalCustomerId": { "type": [ "string", "null" ] }, "insurance": { "type": [ "boolean", "integer" ], "description": "Insure the shipment. Defaults to `false`. Rates always include the insurance price (`insuranceFee`) in `totalChargePrice`; it is charged only when this is `true`." }, "incoterms": { "type": "string", "enum": [ "DDU", "DDP" ] }, "weightUnit": { "type": "string", "enum": [ "gm", "kg", "oz", "lb" ], "example": "lb", "description": "Unit of `weight` for every parcel that does not set its own `weightUnit`. Saved on the shipment, and the dashboard shows the shipment’s weight in it. Defaults to the first parcel’s `weightUnit`." }, "dimUnit": { "type": "string", "enum": [ "cm", "in" ], "example": "in", "description": "Unit of `length`, `width` and `height` for every parcel that does not set its own `dimUnit`. Saved on the shipment. Defaults to the first parcel’s `dimUnit`." }, "parcels": { "$ref": "#/components/schemas/parcels" } } } ] }, "shipmentRates": { "type": "object", "required": [ "parcels", "sender", "recipient", "totalValue", "incoterms" ], "properties": { "totalValue": { "type": "number", "maximum": 2999 }, "insurance": { "type": "boolean", "description": "Insure the shipment. Defaults to `false`. Rates always include the insurance price (`insuranceFee`) in `totalChargePrice`; it is charged only when this is `true`." }, "incoterms": { "type": "string", "enum": [ "DDU", "DDP" ] }, "weightUnit": { "type": "string", "enum": [ "gm", "kg", "oz", "lb" ], "example": "lb", "description": "Unit of `weight` for every parcel that does not set its own `weightUnit`. With no unit on the parcel or here, weights are read as grams." }, "dimUnit": { "type": "string", "enum": [ "cm", "in" ], "example": "in", "description": "Unit of `length`, `width` and `height` for every parcel that does not set its own `dimUnit`. With no unit on the parcel or here, sizes are read as centimeters." }, "sender": { "$ref": "#/components/schemas/RatesAddress" }, "recipient": { "$ref": "#/components/schemas/RatesAddress" }, "parcels": { "$ref": "#/components/schemas/parcels" } } }, "Account": { "title": "Account", "type": "object", "required": [ "name", "displayName", "systemUnits", "email", "notificationEmail", "phone", "emergencyPhone", "website", "isBusiness", "language" ], "properties": { "name": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "systemUnits": { "type": "string", "enum": [ "imperial", "metric" ] }, "email": { "type": "string", "minLength": 1 }, "notificationEmail": { "type": "string", "minLength": 1 }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ], "minLength": 1 }, "emergencyPhone": { "type": [ "string", "null" ], "minLength": 1 }, "taxId": { "type": [ "string", "null" ] }, "taxIdCountry": { "type": [ "object", "null" ], "properties": { "isoCode": { "type": "string" } }, "required": [ "isoCode" ] }, "uid": { "type": "string", "readOnly": true }, "accountNumber": { "type": "string", "readOnly": true }, "parentUid": { "type": [ "string", "null" ], "description": "The `uid` of the parent account when this is a sub-account, `null` otherwise.", "readOnly": true }, "status": { "type": "string", "readOnly": true }, "language": { "type": "string" }, "isBusiness": { "type": [ "boolean", "integer" ] }, "allowBankAccountPayments": { "type": [ "boolean", "integer" ], "readOnly": true }, "metadata": { "type": [ "object", "null" ], "readOnly": true }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time", "readOnly": true }, "addressId": { "type": [ "number", "null" ], "readOnly": true }, "billingAddressId": { "type": [ "number", "null" ], "readOnly": true }, "defaultShipFromId": { "type": [ "number", "null" ], "readOnly": true }, "defaultAddressOnLabelId": { "type": [ "number", "null" ], "readOnly": true }, "defaultReturnAddressId": { "type": [ "number", "null" ], "readOnly": true }, "primaryPaymentShipmentsId": { "type": [ "number", "null" ], "readOnly": true }, "logoId": { "type": [ "number", "null" ], "readOnly": true }, "pickupServiceFallbackId": { "type": [ "number", "null" ], "readOnly": true }, "revision": { "type": [ "number", "null" ], "readOnly": true }, "address": { "anyOf": [ { "$ref": "#/components/schemas/AccountAddressObject" }, { "type": [ "null", "object" ] } ], "description": "Main address of the account." } } }, "parcels": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/Parcel" } }, "parcel_items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/ParcelItem" } }, "CountryBrazil": { "description": "A representation of a Brazil shipment", "allOf": [ { "$ref": "#/components/schemas/AccountAddress" }, { "type": "object", "description": "Brazil Country", "properties": { "country": { "properties": { "isoCode": { "type": "string", "const": "BR" } }, "required": [ "isoCode" ] }, "taxId": { "minLength": 1, "type": "string", "example": "921.778.280-74" } }, "required": [ "country" ] } ] }, "CountryCuba": { "description": "A representation of a Cuba shipment", "allOf": [ { "$ref": "#/components/schemas/AccountAddress" }, { "type": "object", "description": "Cuba Country", "properties": { "country": { "properties": { "isoCode": { "type": "string", "const": "CU" } }, "required": [ "isoCode" ] } }, "required": [ "country" ] } ] }, "CountryColombia": { "description": "A representation of a Colombia shipment", "allOf": [ { "$ref": "#/components/schemas/AccountAddress" }, { "type": "object", "description": "Colombia Country", "properties": { "country": { "properties": { "isoCode": { "type": "string", "const": "CO" } }, "required": [ "isoCode" ] } }, "required": [ "country" ] } ] }, "Category": { "title": "Category", "type": "object", "description": "A shipment content category. Each parcel item declares one.", "required": [ "uid", "name", "slug" ], "properties": { "uid": { "type": "string", "description": "Category UID.", "example": "u40h56jccmdi" }, "name": { "type": "string", "description": "Display name.", "example": "Phone Accessory (no battery)" }, "slug": { "type": "string", "description": "Stable machine name.", "example": "accessory_no_battery" }, "weight": { "type": [ "number", "null" ], "description": "Default weight for one unit, in grams." }, "length": { "type": [ "number", "null" ], "description": "Default length, in centimeters." }, "width": { "type": [ "number", "null" ], "description": "Default width, in centimeters." }, "height": { "type": [ "number", "null" ], "description": "Default height, in centimeters." }, "containsDocuments": { "type": [ "boolean", "integer" ], "description": "Items in this category are documents. `1`/`true` or `0`/`false`." }, "containsOtherDg": { "type": [ "boolean", "integer" ], "description": "Items in this category are dangerous goods other than batteries. `1`/`true` or `0`/`false`." }, "containsLiquids": { "type": [ "boolean", "integer" ], "description": "Items in this category contain liquids. `1`/`true` or `0`/`false`." }, "containsBatteryPi967": { "type": [ "boolean", "integer" ], "description": "Lithium-ion batteries contained in equipment (PI 967). `1`/`true` or `0`/`false`." }, "containsBatteryPi966": { "type": [ "boolean", "integer" ], "description": "Lithium-ion batteries packed with equipment (PI 966). `1`/`true` or `0`/`false`." }, "containsBatteryPi965": { "type": [ "boolean", "integer" ], "description": "Lithium-ion batteries on their own (PI 965). `1`/`true` or `0`/`false`." }, "parentId": { "type": [ "integer", "null" ], "description": "Parent category, when this is a sub-category." } } }, "UId": { "type": "string", "readOnly": true }, "Id": { "type": "number", "format": "int64", "readOnly": true }, "IdReadable": { "type": "number", "format": "int64" }, "Shipment": { "allOf": [ { "type": "object", "properties": { "accountId": { "anyOf": [ { "type": [ "string", "integer" ], "description": "Your account `uid`, as returned by `POST /authentication`, or the `uid` of one of its sub-accounts (`GET /accounts`) to ship for that sub-account." }, { "type": [ "string", "integer" ], "maxLength": 10, "description": "Your account number (`CU…`)." } ] } }, "required": [ "accountId" ] }, { "$ref": "#/components/schemas/formStep2" } ] }, "ShipmentRate": { "allOf": [ { "type": "object", "properties": { "accountId": { "anyOf": [ { "type": "string", "description": "Your account `uid`, as returned by `POST /authentication`." }, { "type": "string", "maxLength": 10, "description": "Your account number (`CU…`)." } ] } }, "required": [ "accountId" ] }, { "$ref": "#/components/schemas/shipmentRates" } ] }, "Transaction": { "title": "Transaction", "type": "object", "properties": { "id": { "description": "Internal ID of the transaction.", "allOf": [ { "$ref": "#/components/schemas/Id" } ] }, "uid": { "description": "Transaction UID.", "allOf": [ { "$ref": "#/components/schemas/UId" } ] }, "type": { "description": "`credit` (money in) or `debit` (money out).", "type": "string", "minLength": 1, "enum": [ "debit", "credit", "refund" ] }, "transType": { "description": "What the transaction is for, for example `Payment`, `Shipment` or `Recharge`.", "type": "string", "minLength": 1, "enum": [ "Shipment", "Payment", "Money Transfer", "Adjustmen", "Fee" ] }, "state": { "description": "Settlement state, for example `cleared` or `pending`.", "type": "string", "minLength": 1, "enum": [ "cleared", "pending" ] }, "referenceNo": { "description": "Reference number of the payment or service.", "type": "string", "minLength": 1 }, "description": { "description": "Description of the transaction.", "type": "string", "minLength": 1 }, "courierName": { "description": "Carrier of the shipment, for shipment charges.", "type": [ "string", "null" ], "minLength": 1 }, "amount": { "description": "Amount, USD.", "type": "number", "minLength": 1 }, "balance": { "description": "Wallet balance after this transaction, USD.", "type": "number", "minLength": 1 }, "accountId": { "description": "Internal ID of the account the transaction belongs to.", "type": "number", "minLength": 1 }, "adjustmentTypeId": { "description": "Internal ID of the adjustment, for manual adjustments.", "type": [ "number", "null" ], "minLength": 1 }, "createdAt": { "description": "When the transaction was booked.", "type": "string", "minLength": 1, "format": "date-time" }, "updatedAt": { "description": "When the transaction last changed.", "type": "string", "minLength": 1, "format": "date-time" } } }, "ShipmentPatch": { "type": "object", "description": "Only the fields you send are changed. A `sender`, `recipient` or `parcels` value you send replaces the stored one as a whole and must be complete.", "minProperties": 1, "properties": { "accountId": { "anyOf": [ { "type": "string", "description": "Your account `uid`, as returned by `POST /authentication`." }, { "type": "string", "maxLength": 10, "description": "Your account number (`CU…`)." } ] }, "sender": { "$ref": "#/components/schemas/sender" }, "recipient": { "$ref": "#/components/schemas/recipient" }, "totalValue": { "type": "number", "maximum": 2999 }, "externalReferenceCode": { "type": "string" }, "externalCustomerId": { "type": "string" }, "insurance": { "type": "boolean", "description": "Insure the shipment. Defaults to `false`. Rates always include the insurance price (`insuranceFee`) in `totalChargePrice`; it is charged only when this is `true`." }, "incoterms": { "type": "string", "enum": [ "DDU", "DDP" ] }, "parcels": { "$ref": "#/components/schemas/parcels" } } }, "AccountPatch": { "type": "object", "description": "The account fields you can change. Send only the ones you want to update.", "minProperties": 1, "properties": { "name": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "systemUnits": { "type": "string", "enum": [ "imperial", "metric" ] }, "email": { "type": "string", "minLength": 1 }, "notificationEmail": { "type": "string", "minLength": 1 }, "website": { "type": "string" }, "phone": { "type": "string", "minLength": 1 }, "emergencyPhone": { "type": "string", "minLength": 1 }, "taxId": { "type": "string" }, "taxIdCountry": { "type": [ "object", "null" ], "properties": { "isoCode": { "type": "string" } }, "required": [ "isoCode" ] }, "language": { "type": "string" }, "isBusiness": { "type": "boolean" }, "address": { "$ref": "#/components/schemas/AccountAddress" } } }, "Service": { "title": "Service", "type": "object", "description": "A shipping service you can rate and buy labels with.", "required": [ "uid", "name" ], "properties": { "uid": { "type": "string", "description": "Service UID. Pass it as `serviceId` when rating or creating a shipment.", "example": "ibrd6l1grbi8" }, "name": { "type": "string", "example": "WeShipYou Air Cuba" }, "modality": { "type": [ "string", "null" ], "description": "How the service moves the parcel (for example `air` or `maritime`).", "example": "air" }, "isPickupService": { "type": "boolean", "description": "The parcel is picked up at the sender address.", "example": false }, "allowPickups": { "type": "boolean", "example": true }, "allowDg": { "type": "boolean", "description": "Dangerous goods are accepted.", "example": false }, "supportsMultiRecipient": { "type": "boolean", "example": false }, "active": { "type": "boolean", "example": true } } }, "AccountAddressObject": { "title": "Account address", "type": "object", "description": "A saved address of an account: a sender, a recipient or both.", "required": [ "uid", "status", "createdAt", "updatedAt" ], "properties": { "uid": { "type": [ "string", "null" ], "description": "Address UID. Use it as `accountAddressId`, or as a sender / recipient `uid` on a shipment.", "example": "g511vge9uyt5" }, "nickname": { "type": [ "string", "null" ], "description": "Name shown in address books." }, "name": { "type": [ "string", "null" ], "description": "Contact name." }, "companyName": { "type": [ "string", "null" ], "description": "Company name." }, "taxId": { "type": [ "string", "null" ], "description": "Tax ID of the contact." }, "email": { "type": [ "string", "null" ], "description": "Contact email." }, "phone": { "type": [ "string", "null" ], "description": "Contact phone, E.164." }, "birthday": { "type": [ "string", "null" ], "format": "date-time", "description": "Contact birthday, when collected." }, "isRecipient": { "type": [ "boolean", "integer", "null" ], "description": "The address can receive shipments. `1`/`true` or `0`/`false`." }, "isSender": { "type": [ "boolean", "integer", "null" ], "description": "The address can send shipments. `1`/`true` or `0`/`false`." }, "isResidential": { "type": [ "boolean", "integer", "null" ], "description": "The address is residential. `1`/`true` or `0`/`false`." }, "status": { "type": [ "string", "null" ], "description": "Record status.", "example": "active" }, "address": { "anyOf": [ { "type": "object", "properties": { "city": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "minLength": 0, "example": "Homestead" }, "state": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "minLength": 0, "example": "Florida" } } } } }, "street": { "description": "Street address, including the building or apartment number.", "type": "string", "minLength": 0, "example": "924 NW 36 Ave" }, "postalCode": { "type": "string", "example": "33033" } } }, { "type": "null" } ], "description": "Street address. Included when the address is read on its own." }, "country": { "anyOf": [ { "$ref": "#/components/schemas/CountryProperty" }, { "type": "null" } ], "description": "Country of the address. Included when the address is read on its own." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the address was saved." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the address last changed." } } }, "ShipmentObject": { "title": "Shipment", "type": "object", "description": "A shipment: what is sent, from whom, to whom, and its label and delivery status.", "required": [ "uid", "state", "incoterms", "weightUnit", "dimUnit", "createdAt", "updatedAt" ], "properties": { "uid": { "type": "string", "description": "Shipment UID. Use it as `shipmentId`.", "example": "sb43c5b9320m" }, "state": { "type": "string", "description": "Lifecycle state, from `created` through `label_created` to `delivered` or `cancelled`.", "example": "created" }, "statusTracking": { "type": [ "string", "null" ], "description": "Latest carrier tracking status, in words." }, "transactionState": { "type": [ "string", "null" ], "description": "Billing state of the shipment, when it was charged or refunded." }, "externalReferenceCode": { "type": [ "string", "null" ], "description": "Your own reference for the shipment." }, "externalCustomerId": { "type": [ "string", "null" ], "description": "Your own customer reference." }, "externalUniqueId": { "type": [ "string", "null" ], "description": "Your own idempotency reference." }, "incoterms": { "type": "string", "enum": [ "DDU", "DDP" ], "description": "Who pays duties: the recipient (`DDU`) or the sender (`DDP`)." }, "weightUnit": { "type": "string", "enum": [ "gm", "kg", "oz", "lb" ], "description": "Unit of `weight`." }, "dimUnit": { "type": "string", "description": "Unit of `length`, `width` and `height`.", "example": "cm" }, "weight": { "type": [ "number", "null" ], "description": "Total weight." }, "length": { "type": [ "number", "null" ], "description": "Length of the box." }, "width": { "type": [ "number", "null" ], "description": "Width of the box." }, "height": { "type": [ "number", "null" ], "description": "Height of the box." }, "totalValue": { "type": [ "number", "null" ], "description": "Declared value of the contents, USD." }, "insurance": { "type": [ "boolean", "integer" ], "description": "The shipment is insured. `1`/`true` or `0`/`false`." }, "insuranceAmount": { "type": [ "number", "null" ], "description": "Insured amount, USD." }, "appliedCouponDiscount": { "type": [ "number", "null" ], "description": "Coupon discount applied to the label price, USD." }, "sellerNotes": { "type": [ "string", "null" ], "description": "Notes from the sender." }, "buyerNotes": { "type": [ "string", "null" ], "description": "Notes from the recipient." }, "labelCreatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the label was bought." }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the carrier delivered the shipment." }, "cancellationReason": { "type": [ "string", "null" ], "description": "Why the shipment was cancelled." }, "cancellationReasonCode": { "type": [ "string", "null" ], "description": "Machine code of the cancellation reason." }, "customsAuthorizations": { "type": "object", "description": "Customs documents the destination requires, and whether the customer can still edit them." }, "sender": { "anyOf": [ { "$ref": "#/components/schemas/ShipmentParty" }, { "type": "null" } ], "description": "The sender. Included when the shipment is read on its own." }, "recipient": { "anyOf": [ { "$ref": "#/components/schemas/ShipmentParty" }, { "type": "null" } ], "description": "The recipient. Included when the shipment is read on its own." }, "parcels": { "type": "array", "items": { "type": "object" }, "description": "The parcels and their items. Included when the shipment is read on its own." }, "parcel_rates": { "type": "array", "description": "The services this shipment can be sent with and their prices. Included in the answer of `POST /shipments` and `PATCH /shipments/{shipmentId}`; pick one and buy it with `POST /shipments/labels`. Their `totalChargePrice` includes insurance (`insuranceFee`) even when the shipment is not insured; see the Rate object.", "items": { "allOf": [ { "$ref": "#/components/schemas/Rate" } ], "required": [ "uid" ] } }, "label": { "type": [ "object", "null" ], "description": "The label, once it is bought. Included when the shipment is read on its own (`GET /shipments/{shipmentId}`).", "properties": { "trackingNumber": { "type": [ "string", "null" ], "description": "The WeShipYou tracking number (`WSY…`). Use it with `GET /tracking/{trackingNumber}` and to cancel the label." } } }, "createdAt": { "type": "string", "format": "date-time", "description": "When the shipment was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the shipment last changed." } } }, "ShipmentPartyAddress": { "type": "object", "description": "A postal address as WeShipYou parsed it.", "properties": { "uid": { "type": "string", "description": "Address UID." }, "houseNumber": { "type": [ "string", "null" ], "description": "House or building number." }, "road": { "type": [ "string", "null" ], "description": "Street name." }, "unit": { "type": [ "string", "null" ], "description": "Apartment, suite or unit." }, "city": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "City name." }, "state": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "isoCode": { "type": [ "string", "null" ], "description": "State code." }, "country": { "anyOf": [ { "type": "object", "properties": { "isoCode": { "type": "string" }, "name": { "type": "string" } } }, { "type": "null" } ] } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "postal_code": { "anyOf": [ { "type": "object", "properties": { "postalCode": { "type": "string" } } }, { "type": "null" } ] } } }, "ShipmentParty": { "type": "object", "description": "The sender or recipient of a shipment.", "properties": { "uid": { "type": "string", "description": "Address book entry UID." }, "nickname": { "type": [ "string", "null" ], "description": "Your label for the entry." }, "companyName": { "type": [ "string", "null" ], "description": "Company name." }, "name": { "type": [ "string", "null" ], "description": "Full name." }, "taxId": { "type": [ "string", "null" ], "description": "Tax ID." }, "email": { "type": [ "string", "null" ], "description": "Email address." }, "phone": { "type": [ "string", "null" ], "description": "Phone number." }, "isResidential": { "type": [ "boolean", "integer" ], "description": "Residential delivery address." }, "status": { "type": "string", "description": "Entry status." }, "address": { "anyOf": [ { "$ref": "#/components/schemas/ShipmentPartyAddress" }, { "type": "null" } ] } } }, "Rate": { "title": "Rate", "type": "object", "description": "A service the shipment can be sent with, and its price in USD.\n\n**`totalChargePrice` always includes the insurance price (`insuranceFee`), even when the shipment is not insured.** Shipments are not insured unless you ask (`insurance: true`), so in most cases subtract `insuranceFee` to get what the label costs:\n\n- label price = `totalChargePrice` − `insuranceFee` when the shipment is not insured, or `totalChargePrice` when it is;\n- plus `pickupFee` and `minimumPickupFee` when the parcels are picked up (`handoverOption: \"pickup\"` in `POST /shipments/labels`).\n\nA coupon lowers that price further.", "properties": { "uid": { "type": "string", "description": "The rate id. Send it as `rateId` to `POST /shipments/labels`." }, "service": { "type": "object", "description": "The shipping service.", "properties": { "uid": { "type": [ "string", "null" ], "description": "The service `uid`." }, "name": { "type": [ "string", "null" ], "description": "The service name." }, "umbrellaName": { "type": [ "string", "null" ], "description": "The carrier or brand the service belongs to." }, "serviceType": { "type": [ "string", "null" ], "description": "`ground`, `air` or `sea`." } } }, "totalChargePrice": { "type": "number", "description": "The quoted price. **Includes `insuranceFee` whether or not the shipment is insured**, and `improvedFoamProtectionFee`. Subtract `insuranceFee` when the shipment is not insured." }, "insuranceFee": { "type": "number", "description": "The price of insuring the shipment with this service. It is already inside `totalChargePrice`; it is charged only when the shipment is insured." }, "improvedFoamProtectionFee": { "type": "number", "description": "The price of improved foam protection, already inside `totalChargePrice`. `0` unless the shipment asks for it." }, "shipmentChargeTotalPrice": { "type": "number", "description": "The price of the shipping service alone; coupon discounts are calculated on it. It is not what the label costs: see `totalChargePrice`." }, "pickupFee": { "type": "number", "description": "Added to the label price when the parcels are picked up." }, "minimumPickupFee": { "type": "number", "description": "Added to the label price when the parcels are picked up." } } } }, "parameters": { "Accept-Language": { "name": "Accept-Language", "in": "header", "description": "Two-letter code of the language for messages: `en`, `es` or `pt`.", "example": "en-US", "required": false, "schema": { "type": "string", "default": "en-US" } } }, "requestBodies": { "Authentication": { "description": "Your WeShipYou login.", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "username", "password" ], "properties": { "username": { "type": "string", "description": "Your WeShipYou username or email.", "default": "{{username}}" }, "password": { "type": "string", "description": "Your password.", "default": "{{password}}" }, "twoFactorToken": { "type": "string", "description": "The current 6-digit code from your authenticator app. Required when two-factor authentication is on for your user.", "pattern": "^[0-9]{6}$", "example": "123456" }, "mode": { "type": "string", "enum": [ "live", "test" ], "default": "live", "description": "`test` on the production server: you log in with your production username and password, and the answer is a **Sandbox** token. The sandbox gets a test copy of your user, your accounts and your memberships (no balance, payment methods or verification data), refreshed on every test login. Every token carries a `livemode` claim: `true` for production, `false` for the sandbox." } } }, "example": { "username": "janedoe", "password": "correct-horse-battery-staple", "twoFactorToken": "123456" } } } }, "Shipment": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" }, "examples": { "manual": { "summary": "Items you declare", "value": { "accountId": "CU1234567", "sender": { "useExistingAddress": false, "nickname": "Main office", "address": { "city": { "name": "Homestead", "state": { "name": "Florida" } }, "street": "924 NW 36 Ave", "postalCode": "33033" }, "name": "John Doe", "companyName": "We Ship You Corp", "taxId": "88-1345985", "taxIdCountry": { "isoCode": "US" }, "phone": "+1 (786) 651-0451", "email": "john.doe@weshipyou.com", "country": { "isoCode": "US" } }, "recipient": { "useExistingAddress": false, "nickname": "Main office", "address": { "city": { "name": "Homestead", "state": { "name": "Florida" } }, "street": "924 NW 36 Ave", "postalCode": "33033" }, "name": "John Doe", "companyName": "We Ship You Corp", "taxId": "88-1345985", "taxIdCountry": { "isoCode": "US" }, "phone": "+1 (786) 651-0451", "email": "john.doe@weshipyou.com", "country": { "isoCode": "US" } }, "totalValue": 2999, "externalReferenceCode": "ORDER-1001", "externalCustomerId": "CUST-42", "insurance": true, "incoterms": "DDU", "parcels": [ { "dimUnit": "cm", "width": 10, "length": 10, "height": 10, "weightUnit": "gm", "weight": 100, "parcel_items": [ { "sku": "SKU-WSY-EXAMPLE", "description": "Play Station 4", "category": { "slug": "board_games" }, "price": 450, "qty": 1, "originCountry": { "isoCode": "JP" }, "weight": 2.5, "currency": "USD" } ] } ] } }, "locker": { "summary": "From locker items", "value": { "accountId": "CU1234567", "sender": { "useExistingAddress": false, "nickname": "Main office", "address": { "city": { "name": "Homestead", "state": { "name": "Florida" } }, "street": "924 NW 36 Ave", "postalCode": "33033" }, "name": "John Doe", "companyName": "We Ship You Corp", "taxId": "88-1345985", "taxIdCountry": { "isoCode": "US" }, "phone": "+1 (786) 651-0451", "email": "john.doe@weshipyou.com", "country": { "isoCode": "US" } }, "recipient": { "useExistingAddress": false, "nickname": "Main office", "address": { "city": { "name": "Homestead", "state": { "name": "Florida" } }, "street": "924 NW 36 Ave", "postalCode": "33033" }, "name": "John Doe", "companyName": "We Ship You Corp", "taxId": "88-1345985", "taxIdCountry": { "isoCode": "US" }, "phone": "+1 (786) 651-0451", "email": "john.doe@weshipyou.com", "country": { "isoCode": "US" } }, "totalValue": 65, "externalReferenceCode": "ORDER-1002", "insurance": true, "incoterms": "DDU", "parcels": [ { "dimUnit": "cm", "width": 20, "length": 30, "height": 15, "weightUnit": "gm", "weight": 1500, "parcel_items": [ { "forwardingOrderItemId": "ltinx3lzbjxv", "description": "Phone case", "category": { "slug": "accessory_no_battery" }, "price": 15, "qty": 1, "currency": "USD" }, { "forwardingOrderItemId": "9wq2mf7kx0cd", "description": "Board game", "category": { "slug": "board_games" }, "price": 50, "qty": 1, "currency": "USD" } ] } ] } } } } }, "description": "The shipment to create.", "required": true }, "ShipmentRate": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentRate" }, "examples": { "manual": { "summary": "Items you declare", "value": { "accountId": "CU1234567", "totalValue": 2999, "insurance": true, "incoterms": "DDU", "sender": { "address": { "city": { "name": "Homestead", "state": { "name": "Florida" } }, "street": "924 NW 36 Ave", "postalCode": "33033" }, "country": { "isoCode": "US" } }, "recipient": { "address": { "city": { "name": "Homestead", "state": { "name": "Florida" } }, "street": "924 NW 36 Ave", "postalCode": "33033" }, "country": { "isoCode": "US" } }, "parcels": [ { "dimUnit": "cm", "width": 10, "length": 10, "height": 10, "weightUnit": "gm", "weight": 100, "parcel_items": [ { "sku": "SKU-WSY-EXAMPLE", "description": "Play Station 4", "category": { "slug": "board_games" }, "price": 450, "qty": 1, "originCountry": { "isoCode": "JP" }, "weight": 2.5, "currency": "USD" } ] } ] } }, "locker": { "summary": "From locker items", "value": { "accountId": "CU1234567", "totalValue": 65, "insurance": true, "incoterms": "DDU", "sender": { "address": { "city": { "name": "Homestead", "state": { "name": "Florida" } }, "street": "924 NW 36 Ave", "postalCode": "33033" }, "country": { "isoCode": "US" } }, "recipient": { "address": { "city": { "name": "Homestead", "state": { "name": "Florida" } }, "street": "924 NW 36 Ave", "postalCode": "33033" }, "country": { "isoCode": "US" } }, "parcels": [ { "dimUnit": "cm", "width": 20, "length": 30, "height": 15, "weightUnit": "gm", "weight": 1500, "parcel_items": [ { "forwardingOrderItemId": "ltinx3lzbjxv", "description": "Phone case", "category": { "slug": "accessory_no_battery" }, "price": 15, "qty": 1, "currency": "USD" }, { "forwardingOrderItemId": "9wq2mf7kx0cd", "description": "Board game", "category": { "slug": "board_games" }, "price": 50, "qty": 1, "currency": "USD" } ] } ] } } } } }, "description": "The shipment to create.", "required": true }, "Recharge": { "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethod": { "description": "How to pay. Omit it to pay from your wallet balance (add funds first with `POST /add-funds`); `\"credit_line\"` for accounts with a credit line.", "oneOf": [ { "type": "string", "enum": [ "credit_line" ] }, { "type": "object", "properties": { "isWallet": { "const": true } } } ] }, "accountUid": { "type": "string", "description": "The account `uid`. Optional when you belong to a single account." }, "rechargeable_product": { "type": "object", "properties": { "id": { "type": "number" } } }, "scheduleDate": { "type": [ "string", "null" ], "format": "date-time" }, "amount": { "type": "number" }, "account_rechargeable_contact": { "type": "object", "properties": { "name": { "type": "string" }, "accountNumber": { "type": "string" } } } } }, "example": { "accountUid": "45e3hygz8zkv", "rechargeable_product": { "id": 34 }, "amount": 20, "account_rechargeable_contact": { "name": "Maria Perez", "accountNumber": "+5352345678" } } } }, "description": "The shipment to create.", "required": true }, "AddFunds": { "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethod": { "type": "string", "description": "How you paid: `zelle` (the default) or `crypto`.", "default": "zelle", "enum": [ "zelle", "crypto" ] }, "accountUid": { "type": "string", "description": "The account `uid`. Optional when you belong to a single account." }, "transaction": { "type": "object", "properties": { "zelleTransaction": { "type": "string", "description": "The Zelle transaction ID, for `zelle`." }, "amount": { "type": "number", "description": "Amount you sent, USD. Required for `zelle` and `crypto`." }, "chargeUid": { "type": "string", "description": "The code of the paid Coinbase Commerce charge, for `crypto`." } } } } }, "example": { "paymentMethod": "zelle", "accountUid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "transaction": { "zelleTransaction": "ZL-20261001-0001", "amount": 20 } } } }, "description": "The shipment to create.", "required": true }, "AddSubAccount": { "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "accountUid": { "type": "string", "description": "The `uid` of the parent account, one you belong to. Optional when you belong to a single account (the sub-account is created under it)." }, "externalAccountNumber": { "type": "string" }, "name": { "type": "string" } } }, { "$ref": "#/components/schemas/Account" } ] }, "example": { "accountUid": "h4jupn7wtfqp", "externalAccountNumber": "STORE-7", "name": "Jane's Store Orlando", "displayName": "Jane's Store Orlando", "systemUnits": "imperial", "email": "orlando@janesstore.com", "notificationEmail": "orlando-orders@janesstore.com", "website": "https://janesstore.com", "phone": "+1 (786) 651-0451", "emergencyPhone": "+1 (786) 651-0452", "taxId": "88-1345985", "taxIdCountry": { "isoCode": "US" }, "language": "en-US", "isBusiness": true } } }, "description": "The sub-account to create.", "required": true } }, "securitySchemes": { "JWT": { "description": "The access token from `POST /authentication` (valid until its `exp`), sent as `Authorization: Bearer `.", "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "examples": {} }, "x-webhooks": {}, "security": [ { "JWT": [] } ] }