{ "auth": { "bearer": [ { "key": "token", "type": "string", "value": "{{apiKey}}" } ], "type": "bearer" }, "info": { "_postman_id": "207bbb69-3482-5302-9921-1307d1d69c70", "description": "The Boxmile API for your own integrations: rate shipments, track parcels, check addresses and read your balance, with an API key. JSON fields are lowerCamelCase; money is integer US cents in ...Cents fields; timestamps are RFC 3339 UTC. Errors are RFC 9457 problem+json with a stable code. Every answer carries X-Request-Id, and every keyed answer the IETF RateLimit-Policy and RateLimit headers. Within v1, changes are additive only.\n\n## Authentication\n\nEvery request except GET /v1/openapi sends `Authorization: Bearer {{apiKey}}`. Create a key in the\nBoxmile web app under Settings > API keys and paste it into the collection's current value of\n`apiKey`, never its initial value, so it is never exported or synced. A key acts for its own\nworkspace only. Live keys (`boxmile_sk_live_...`) act on real data; test keys\n(`boxmile_sk_test_...`) are read-only. Each operation names the scope it needs (Permission).\n\n## Quick start\n\n1. Import this collection. It needs no environment file.\n2. In the collection's **Variables**, keep `baseUrl` and paste your key into `apiKey`'s **Current value**.\n3. Send **Catalog > List the carrier services a key can rate** to check the key.\n4. Send **Rates > Rate a parcel**. A 202 answer is still rating: send **Read a rate request**\n with its `id` after the Retry-After seconds.\n\nErrors are RFC 9457 `application/problem+json`; branch on `code`. Every answer carries\n`X-Request-Id`; quote it when reporting a problem. Rate limits are in the `RateLimit` headers.", "name": "BoxMile-Public-v1", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "version": "1.0.0-alpha.1" }, "item": [ { "description": "This API's own document and the carrier services a key can rate.", "id": "2732ae3f-1b50-5f4c-b76e-2c8f9839770c", "item": [ { "id": "06d928f9-4603-5720-9e07-f1b526d4ba71", "name": "Read this API's OpenAPI document", "request": { "auth": { "type": "noauth" }, "description": "**Read this API's OpenAPI document**\n\nThe reviewed OpenAPI 3.1 document of this API. It needs no key; reads count against a limit per client address.\n\nPermission: `public`.\n\n**Responses**\n\n- `200` OK: The OpenAPI document.\n- `429` Too Many Requests: The bucket is empty. Wait Retry-After seconds. (`api.rate_limited`)", "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "openapi" ], "raw": "{{baseUrl}}/v1/openapi" } }, "response": [ { "_postman_previewlanguage": "json", "body": "{\n \"openapi\": \"3.1.0\",\n \"info\": {\n \"title\": \"Boxmile Public API\",\n \"version\": \"1.0.0\"\n }\n}", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "" } ], "name": "200 The OpenAPI document.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "openapi" ], "raw": "{{baseUrl}}/v1/openapi" } }, "status": "OK" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"Too many requests. Wait the number of seconds in the Retry-After header, then try again.\",\n \"status\": 429,\n \"code\": \"api.rate_limited\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 429, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" }, { "key": "Retry-After", "value": "" } ], "name": "429 The bucket is empty. Wait Retry-After seconds.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "openapi" ], "raw": "{{baseUrl}}/v1/openapi" } }, "status": "Too Many Requests" } ] }, { "id": "3f40d792-4a18-594e-b9e1-a825307b4555", "name": "List the carrier services a key can rate", "request": { "description": "**List the carrier services a key can rate**\n\nEvery carrier service this deployment offers, in its configured order. Services name the carrier and the carrier's service, never the account or partner that fulfils it. The list has no further page.\n\nPermission: `rates.read`.\n\n**Responses**\n\n- `200` OK: The services.\n- `401` Unauthorized: The key is missing, malformed, unknown, revoked or expired. (`authentication.required`)\n- `403` Forbidden: The key lacks this operation's scope, or its workspace is not active. (`access.denied`)\n- `429` Too Many Requests: The bucket is empty. Wait Retry-After seconds. (`api.rate_limited`)\n- `503` Service Unavailable: Rating is not configured on this deployment. (`service.unavailable`)", "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "services" ], "raw": "{{baseUrl}}/v1/services" } }, "response": [ { "_postman_previewlanguage": "json", "body": "{\n \"object\": \"list\",\n \"items\": [\n {\n \"object\": \"service\",\n \"code\": \"USPS_GROUND_ADVANTAGE\",\n \"carrier\": \"usps\",\n \"carrierName\": \"USPS\",\n \"serviceName\": \"USPS Ground Advantage\"\n }\n ],\n \"nextCursor\": null\n}", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "" } ], "name": "200 The services.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "services" ], "raw": "{{baseUrl}}/v1/services" } }, "status": "OK" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"Sign in to continue.\",\n \"status\": 401,\n \"code\": \"authentication.required\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "401 The key is missing, malformed, unknown, revoked or expired.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "services" ], "raw": "{{baseUrl}}/v1/services" } }, "status": "Unauthorized" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"You do not have permission to perform this action.\",\n \"status\": 403,\n \"code\": \"access.denied\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 403, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "403 The key lacks this operation's scope, or its workspace is not active.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "services" ], "raw": "{{baseUrl}}/v1/services" } }, "status": "Forbidden" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"Too many requests. Wait the number of seconds in the Retry-After header, then try again.\",\n \"status\": 429,\n \"code\": \"api.rate_limited\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 429, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" }, { "key": "Retry-After", "value": "" } ], "name": "429 The bucket is empty. Wait Retry-After seconds.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "services" ], "raw": "{{baseUrl}}/v1/services" } }, "status": "Too Many Requests" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"This feature is not available yet. Try again later.\",\n \"status\": 503,\n \"code\": \"service.unavailable\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 503, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "503 Rating is not configured on this deployment.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "services" ], "raw": "{{baseUrl}}/v1/services" } }, "status": "Service Unavailable" } ] } ], "name": "Catalog" }, { "description": "Prices for a parcel from the same pipeline as the web app. Nothing is bought.", "id": "466d4d92-a1f4-5664-ac85-3f44110a0ba8", "item": [ { "id": "10989dba-1d61-50f9-a54f-b553eec125bc", "name": "Rate a parcel", "request": { "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\n \"toAddress\": {\n \"name\": \"Ada Lovelace\",\n \"line1\": \"34 Example Road\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"postalCode\": \"10001\",\n \"country\": \"US\",\n \"residential\": true\n },\n \"parcel\": {\n \"weightOz\": 12,\n \"lengthIn\": 6,\n \"widthIn\": 4,\n \"heightIn\": 2\n },\n \"services\": [\n \"USPS_GROUND_ADVANTAGE\",\n \"UPS_GROUND\"\n ]\n}" }, "description": "**Rate a parcel**\n\nRates one parcel to one destination, from fromAddress or else your workspace's default origin, for the services named (default: every service in GET /v1/services). Each price comes from the same rating and pricing pipeline as the Boxmile web app, and nothing is bought. The server waits a few seconds: a finished request answers 201, one still rating answers 202 with a Location to poll. A service with no price is listed under unavailable with a reason. Each rate's id is the quote, and its price holds until expiresAt (15 minutes). Test keys can rate.\n\nPermission: `rates.write`.\n\n**Body** `application/json` (required): `RateRequestInput`\n\nRequired fields: `toAddress`, `parcel`.\n\n**Responses**\n\n- `201` Created: Rated. Location is this rate request.\n- `202` Accepted: Still rating after the server's wait (a few seconds). Poll Location; Retry-After is a hint in seconds.\n- `400` Bad Request: The body is not valid JSON, has a field this API does not know, misses a required field, has a value out of range, or names a service the catalog does not offer. (`request.invalid`)\n- `401` Unauthorized: The key is missing, malformed, unknown, revoked or expired. (`authentication.required`)\n- `403` Forbidden: The key lacks this operation's scope, or its workspace is not active. (`access.denied`)\n- `429` Too Many Requests: The bucket is empty. Wait Retry-After seconds. (`api.rate_limited`)\n- `503` Service Unavailable: Rating is not configured on this deployment. (`service.unavailable`)", "header": [ { "key": "Content-Type", "value": "application/json" } ], "method": "POST", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "rates" ], "raw": "{{baseUrl}}/v1/rates" } }, "response": [ { "_postman_previewlanguage": "json", "body": "{\n \"object\": \"rate_request\",\n \"id\": \"0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\",\n \"status\": \"completed\",\n \"failureReason\": null,\n \"createdAt\": \"2026-10-20T03:00:00Z\",\n \"rates\": [\n {\n \"object\": \"rate\",\n \"id\": \"0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e01\",\n \"service\": \"USPS_GROUND_ADVANTAGE\",\n \"carrier\": \"usps\",\n \"carrierName\": \"USPS\",\n \"serviceName\": \"USPS Ground Advantage\",\n \"amountCents\": 725,\n \"currency\": \"usd\",\n \"expiresAt\": \"2026-10-20T03:15:00Z\"\n }\n ],\n \"unavailable\": [\n {\n \"service\": \"UPS_GROUND\",\n \"reason\": \"no_rate\"\n }\n ]\n}", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "" }, { "key": "Location", "value": "" } ], "name": "201 Rated. Location is this rate request.", "originalRequest": { "header": [], "method": "POST", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "rates" ], "raw": "{{baseUrl}}/v1/rates" } }, "status": "Created" }, { "_postman_previewlanguage": "json", "body": "{\n \"object\": \"rate_request\",\n \"id\": \"0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\",\n \"status\": \"pending\",\n \"failureReason\": null,\n \"createdAt\": \"2026-10-20T03:00:00Z\",\n \"rates\": [],\n \"unavailable\": []\n}", "code": 202, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "" }, { "key": "Retry-After", "value": "" }, { "key": "Location", "value": "" } ], "name": "202 Still rating after the server's wait (a few seconds).", "originalRequest": { "header": [], "method": "POST", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "rates" ], "raw": "{{baseUrl}}/v1/rates" } }, "status": "Accepted" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"Check the request and try again.\",\n \"status\": 400,\n \"code\": \"request.invalid\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 400, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "400 The body is not valid JSON, has a field this API does not know, misses a require", "originalRequest": { "header": [], "method": "POST", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "rates" ], "raw": "{{baseUrl}}/v1/rates" } }, "status": "Bad Request" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"Sign in to continue.\",\n \"status\": 401,\n \"code\": \"authentication.required\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "401 The key is missing, malformed, unknown, revoked or expired.", "originalRequest": { "header": [], "method": "POST", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "rates" ], "raw": "{{baseUrl}}/v1/rates" } }, "status": "Unauthorized" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"You do not have permission to perform this action.\",\n \"status\": 403,\n \"code\": \"access.denied\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 403, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "403 The key lacks this operation's scope, or its workspace is not active.", "originalRequest": { "header": [], "method": "POST", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "rates" ], "raw": "{{baseUrl}}/v1/rates" } }, "status": "Forbidden" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"Too many requests. Wait the number of seconds in the Retry-After header, then try again.\",\n \"status\": 429,\n \"code\": \"api.rate_limited\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 429, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" }, { "key": "Retry-After", "value": "" } ], "name": "429 The bucket is empty. Wait Retry-After seconds.", "originalRequest": { "header": [], "method": "POST", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "rates" ], "raw": "{{baseUrl}}/v1/rates" } }, "status": "Too Many Requests" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"This feature is not available yet. Try again later.\",\n \"status\": 503,\n \"code\": \"service.unavailable\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 503, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "503 Rating is not configured on this deployment.", "originalRequest": { "header": [], "method": "POST", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "rates" ], "raw": "{{baseUrl}}/v1/rates" } }, "status": "Service Unavailable" } ] }, { "id": "afd5ad11-e4c1-5f95-9e37-3e70661a4fb0", "name": "Read a rate request", "request": { "description": "**Read a rate request**\n\nA rate request this API key made, as it stands now; another key, even of the same workspace, gets 404. While status is pending, poll again after Retry-After seconds.\n\nPermission: `rates.read`.\n\n**Parameters**\n\n- `id` (path, required, string, uuid): The rate request's id.\n\n**Responses**\n\n- `200` OK: The rate request.\n- `400` Bad Request: The id is not a UUID. (`request.invalid`)\n- `401` Unauthorized: The key is missing, malformed, unknown, revoked or expired. (`authentication.required`)\n- `403` Forbidden: The key lacks this operation's scope, or its workspace is not active. (`access.denied`)\n- `429` Too Many Requests: The bucket is empty. Wait Retry-After seconds. (`api.rate_limited`)\n- `404` Not Found: No rate request with this id was made by your workspace's API keys. (`resource.not_found`)\n- `503` Service Unavailable: Rating is not configured on this deployment. (`service.unavailable`)", "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "rate-requests", ":id" ], "raw": "{{baseUrl}}/v1/rate-requests/:id", "variable": [ { "description": "The rate request's id.", "key": "id", "value": "0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f" } ] } }, "response": [ { "_postman_previewlanguage": "json", "body": "{\n \"object\": \"rate_request\",\n \"id\": \"0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\",\n \"status\": \"completed\",\n \"failureReason\": null,\n \"createdAt\": \"2026-10-20T03:00:00Z\",\n \"rates\": [\n {\n \"object\": \"rate\",\n \"id\": \"0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e01\",\n \"service\": \"USPS_GROUND_ADVANTAGE\",\n \"carrier\": \"usps\",\n \"carrierName\": \"USPS\",\n \"serviceName\": \"USPS Ground Advantage\",\n \"amountCents\": 725,\n \"currency\": \"usd\",\n \"expiresAt\": \"2026-10-20T03:15:00Z\"\n }\n ],\n \"unavailable\": [\n {\n \"service\": \"UPS_GROUND\",\n \"reason\": \"no_rate\"\n }\n ]\n}", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "" } ], "name": "200 The rate request.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "rate-requests", ":id" ], "raw": "{{baseUrl}}/v1/rate-requests/:id" } }, "status": "OK" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"Check the request and try again.\",\n \"status\": 400,\n \"code\": \"request.invalid\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 400, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "400 The id is not a UUID.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "rate-requests", ":id" ], "raw": "{{baseUrl}}/v1/rate-requests/:id" } }, "status": "Bad Request" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"Sign in to continue.\",\n \"status\": 401,\n \"code\": \"authentication.required\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "401 The key is missing, malformed, unknown, revoked or expired.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "rate-requests", ":id" ], "raw": "{{baseUrl}}/v1/rate-requests/:id" } }, "status": "Unauthorized" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"You do not have permission to perform this action.\",\n \"status\": 403,\n \"code\": \"access.denied\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 403, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "403 The key lacks this operation's scope, or its workspace is not active.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "rate-requests", ":id" ], "raw": "{{baseUrl}}/v1/rate-requests/:id" } }, "status": "Forbidden" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"The requested resource was not found.\",\n \"status\": 404,\n \"code\": \"resource.not_found\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 404, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "404 No rate request with this id was made by your workspace's API keys.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "rate-requests", ":id" ], "raw": "{{baseUrl}}/v1/rate-requests/:id" } }, "status": "Not Found" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"Too many requests. Wait the number of seconds in the Retry-After header, then try again.\",\n \"status\": 429,\n \"code\": \"api.rate_limited\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 429, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" }, { "key": "Retry-After", "value": "" } ], "name": "429 The bucket is empty. Wait Retry-After seconds.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "rate-requests", ":id" ], "raw": "{{baseUrl}}/v1/rate-requests/:id" } }, "status": "Too Many Requests" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"This feature is not available yet. Try again later.\",\n \"status\": 503,\n \"code\": \"service.unavailable\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 503, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "503 Rating is not configured on this deployment.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "rate-requests", ":id" ], "raw": "{{baseUrl}}/v1/rate-requests/:id" } }, "status": "Service Unavailable" } ] } ], "name": "Rates" }, { "description": "Delivery status and carrier scans of your workspace's parcels.", "id": "06812a88-1154-5597-b509-02bf4e6d65f9", "item": [ { "id": "9bdf230d-6da6-5b99-9e1a-8801f84dd0db", "name": "Track a parcel", "request": { "description": "**Track a parcel**\n\nThe delivery status and carrier scans, newest first, of the parcel with this tracking number that your workspace shipped. A parcel of another workspace, a voided label and an unknown number all answer 404. Test keys can track.\n\nPermission: `labels.read`.\n\n**Parameters**\n\n- `trackingNumber` (path, required, string): The carrier tracking number, exactly as on the label (letters and digits).\n\n**Responses**\n\n- `200` OK: The parcel's tracking.\n- `400` Bad Request: The tracking number is not 4 to 64 letters and digits. (`request.invalid`)\n- `401` Unauthorized: The key is missing, malformed, unknown, revoked or expired. (`authentication.required`)\n- `403` Forbidden: The key lacks this operation's scope, or its workspace is not active. (`access.denied`)\n- `429` Too Many Requests: The bucket is empty. Wait Retry-After seconds. (`api.rate_limited`)\n- `404` Not Found: Your workspace has no live parcel with this tracking number. (`resource.not_found`)\n- `503` Service Unavailable: Tracking is not configured on this deployment, or its store is busy. Try again later. (`service.unavailable`)", "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "tracking", ":trackingNumber" ], "raw": "{{baseUrl}}/v1/tracking/:trackingNumber", "variable": [ { "description": "The carrier tracking number, exactly as on the label (letters and digits).", "key": "trackingNumber", "value": "1Z999AA10123456784" } ] } }, "response": [ { "_postman_previewlanguage": "json", "body": "{\n \"object\": \"tracking\",\n \"trackingNumber\": \"1Z999AA10123456784\",\n \"carrier\": \"ups\",\n \"carrierName\": \"UPS\",\n \"status\": \"in_transit\",\n \"events\": [\n {\n \"id\": \"0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e10\",\n \"occurredAt\": \"2026-10-20T02:10:00Z\",\n \"status\": \"In transit\",\n \"description\": \"Departed facility\",\n \"location\": \"Louisville, KY\"\n }\n ]\n}", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "" } ], "name": "200 The parcel's tracking.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "tracking", ":trackingNumber" ], "raw": "{{baseUrl}}/v1/tracking/:trackingNumber" } }, "status": "OK" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"Check the request and try again.\",\n \"status\": 400,\n \"code\": \"request.invalid\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 400, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "400 The tracking number is not 4 to 64 letters and digits.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "tracking", ":trackingNumber" ], "raw": "{{baseUrl}}/v1/tracking/:trackingNumber" } }, "status": "Bad Request" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"Sign in to continue.\",\n \"status\": 401,\n \"code\": \"authentication.required\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "401 The key is missing, malformed, unknown, revoked or expired.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "tracking", ":trackingNumber" ], "raw": "{{baseUrl}}/v1/tracking/:trackingNumber" } }, "status": "Unauthorized" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"You do not have permission to perform this action.\",\n \"status\": 403,\n \"code\": \"access.denied\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 403, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "403 The key lacks this operation's scope, or its workspace is not active.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "tracking", ":trackingNumber" ], "raw": "{{baseUrl}}/v1/tracking/:trackingNumber" } }, "status": "Forbidden" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"The requested resource was not found.\",\n \"status\": 404,\n \"code\": \"resource.not_found\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 404, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "404 Your workspace has no live parcel with this tracking number.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "tracking", ":trackingNumber" ], "raw": "{{baseUrl}}/v1/tracking/:trackingNumber" } }, "status": "Not Found" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"Too many requests. Wait the number of seconds in the Retry-After header, then try again.\",\n \"status\": 429,\n \"code\": \"api.rate_limited\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 429, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" }, { "key": "Retry-After", "value": "" } ], "name": "429 The bucket is empty. Wait Retry-After seconds.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "tracking", ":trackingNumber" ], "raw": "{{baseUrl}}/v1/tracking/:trackingNumber" } }, "status": "Too Many Requests" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"This feature is not available yet. Try again later.\",\n \"status\": 503,\n \"code\": \"service.unavailable\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 503, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "503 Tracking is not configured on this deployment, or its store is busy.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "tracking", ":trackingNumber" ], "raw": "{{baseUrl}}/v1/tracking/:trackingNumber" } }, "status": "Service Unavailable" } ] } ], "name": "Tracking" }, { "description": "Address checks. Nothing is stored and no carrier is asked.", "id": "4979aca9-535f-50e0-bf45-66c5a922752d", "item": [ { "id": "0e7d527d-1d71-548c-b576-b0ae22e35dca", "name": "Validate an address", "request": { "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\n \"line1\": \"34 Example Road\",\n \"city\": \"New York\",\n \"state\": \"new york\",\n \"postalCode\": \"100011234\"\n}" }, "description": "**Validate an address**\n\nChecks one address's form and answers it standardized. Every address needs line1 and city, and a country Boxmile recognizes and may ship to (sanctioned countries and regions are refused). A US-domestic address (US and the USPS-domestic territories) also needs a USPS state, by code or name, and a 5- or 9-digit ZIP. The state becomes its code, a 9-digit ZIP is written 12345-6789 and runs of spaces become one. No carrier is asked, so carrierVerified is false: a valid address is unverified, or standardized when its form changed. An address that fails a check is a 200 with status invalid and each field's reason. Nothing is stored. Test keys can validate.\n\nPermission: `addresses.read`.\n\n**Body** `application/json` (required): `Address`. A postal address. Give postalCode, or city and state. A destination without line1 is rated at a placeholder street, which does not change a price.\n\n**Responses**\n\n- `200` OK: The address's validation.\n- `400` Bad Request: The body is not an Address: not JSON, an unknown field, a value that is not text, text over 200 characters, or a country that is not two letters. (`request.invalid`)\n- `401` Unauthorized: The key is missing, malformed, unknown, revoked or expired. (`authentication.required`)\n- `403` Forbidden: The key lacks this operation's scope, or its workspace is not active. (`access.denied`)\n- `429` Too Many Requests: The bucket is empty. Wait Retry-After seconds. (`api.rate_limited`)", "header": [ { "key": "Content-Type", "value": "application/json" } ], "method": "POST", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "addresses", "validate" ], "raw": "{{baseUrl}}/v1/addresses/validate" } }, "response": [ { "_postman_previewlanguage": "json", "body": "{\n \"object\": \"address_validation\",\n \"status\": \"standardized\",\n \"carrierVerified\": false,\n \"address\": {\n \"line1\": \"34 Example Road\",\n \"line2\": null,\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"postalCode\": \"10001-1234\",\n \"country\": \"US\"\n },\n \"errors\": [],\n \"notices\": [\n \"review_formatting\",\n \"not_verified\"\n ]\n}", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "" } ], "name": "200 The address's validation.", "originalRequest": { "header": [], "method": "POST", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "addresses", "validate" ], "raw": "{{baseUrl}}/v1/addresses/validate" } }, "status": "OK" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"Check the request and try again.\",\n \"status\": 400,\n \"code\": \"request.invalid\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 400, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "400 The body is not an Address: not JSON, an unknown field, a value that is not text", "originalRequest": { "header": [], "method": "POST", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "addresses", "validate" ], "raw": "{{baseUrl}}/v1/addresses/validate" } }, "status": "Bad Request" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"Sign in to continue.\",\n \"status\": 401,\n \"code\": \"authentication.required\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "401 The key is missing, malformed, unknown, revoked or expired.", "originalRequest": { "header": [], "method": "POST", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "addresses", "validate" ], "raw": "{{baseUrl}}/v1/addresses/validate" } }, "status": "Unauthorized" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"You do not have permission to perform this action.\",\n \"status\": 403,\n \"code\": \"access.denied\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 403, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "403 The key lacks this operation's scope, or its workspace is not active.", "originalRequest": { "header": [], "method": "POST", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "addresses", "validate" ], "raw": "{{baseUrl}}/v1/addresses/validate" } }, "status": "Forbidden" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"Too many requests. Wait the number of seconds in the Retry-After header, then try again.\",\n \"status\": 429,\n \"code\": \"api.rate_limited\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 429, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" }, { "key": "Retry-After", "value": "" } ], "name": "429 The bucket is empty. Wait Retry-After seconds.", "originalRequest": { "header": [], "method": "POST", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "addresses", "validate" ], "raw": "{{baseUrl}}/v1/addresses/validate" } }, "status": "Too Many Requests" } ] } ], "name": "Addresses" }, { "description": "Your workspace's wallet totals. Read only.", "id": "da545ff9-f96b-58ac-809c-f9efec3bfa9e", "item": [ { "id": "29dac7bf-261f-57f7-912e-c432c79ff574", "name": "Read your balance", "request": { "description": "**Read your balance**\n\nYour workspace's wallet totals, the same figures the Boxmile web app's billing summary shows. availableCents is what label purchases can spend from: the balance less what is reserved and, while it is on, the carrier-adjustment reserve; it can be negative. reservedCents is the total held for purchases and disputes in flight. No hold by order, payment method or funding reference is shown. Test keys can read the balance.\n\nPermission: `balance.read`.\n\n**Responses**\n\n- `200` OK: The balance.\n- `401` Unauthorized: The key is missing, malformed, unknown, revoked or expired. (`authentication.required`)\n- `403` Forbidden: The key lacks this operation's scope, or its workspace is not active. (`access.denied`)\n- `429` Too Many Requests: The bucket is empty. Wait Retry-After seconds. (`api.rate_limited`)\n- `503` Service Unavailable: The wallet could not be read in time. Try again later. (`service.unavailable`)", "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "balance" ], "raw": "{{baseUrl}}/v1/balance" } }, "response": [ { "_postman_previewlanguage": "json", "body": "{\n \"object\": \"balance\",\n \"availableCents\": 12345,\n \"reservedCents\": 300,\n \"currency\": \"usd\"\n}", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Request-Id", "value": "" } ], "name": "200 The balance.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "balance" ], "raw": "{{baseUrl}}/v1/balance" } }, "status": "OK" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"Sign in to continue.\",\n \"status\": 401,\n \"code\": \"authentication.required\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "401 The key is missing, malformed, unknown, revoked or expired.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "balance" ], "raw": "{{baseUrl}}/v1/balance" } }, "status": "Unauthorized" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"You do not have permission to perform this action.\",\n \"status\": 403,\n \"code\": \"access.denied\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 403, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "403 The key lacks this operation's scope, or its workspace is not active.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "balance" ], "raw": "{{baseUrl}}/v1/balance" } }, "status": "Forbidden" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"Too many requests. Wait the number of seconds in the Retry-After header, then try again.\",\n \"status\": 429,\n \"code\": \"api.rate_limited\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 429, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" }, { "key": "Retry-After", "value": "" } ], "name": "429 The bucket is empty. Wait Retry-After seconds.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "balance" ], "raw": "{{baseUrl}}/v1/balance" } }, "status": "Too Many Requests" }, { "_postman_previewlanguage": "json", "body": "{\n \"type\": \"about:blank\",\n \"title\": \"This feature is not available yet. Try again later.\",\n \"status\": 503,\n \"code\": \"service.unavailable\",\n \"params\": {},\n \"locale\": \"en\",\n \"instance\": \"urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f\"\n}", "code": 503, "header": [ { "key": "Content-Type", "value": "application/problem+json" }, { "key": "X-Request-Id", "value": "" } ], "name": "503 The wallet could not be read in time.", "originalRequest": { "header": [], "method": "GET", "url": { "host": [ "{{baseUrl}}" ], "path": [ "v1", "balance" ], "raw": "{{baseUrl}}/v1/balance" } }, "status": "Service Unavailable" } ] } ], "name": "Balance" } ], "variable": [ { "key": "baseUrl", "type": "string", "value": "https://api.boxmile.com" }, { "key": "apiKey", "type": "string", "value": "" } ] }