{ "openapi": "3.1.0", "info": { "title": "Spoke Connect API", "description": "This is the documentation of the Spoke Connect API HTTP endpoints. The Connect\nAPI is how a retailer creates, tracks, and hands off its deliveries in Spoke\nprogrammatically.\n\n# Introduction\n\nThe Spoke Connect API is an HTTP API that lets you operate on your orders\nprogrammatically. Use it to create, edit, delete, list, and retrieve orders,\nsubmit them to a courier and withdraw them before they ship, and download\nprintable PDF labels. Read-only endpoints expose the couriers and pickup\nlocations your orders reference.\n\nSpoke offers no programming SDKs for the Connect API. Call the endpoints\ndocumented on this page directly, or generate a client from the\n[OpenAPI spec](/openapi-connect-v1.json).\n\nFor worked examples of the flows a retailer integration needs, see the\n[Usage Examples](/docs/api-examples).\n\n# Using the API\n\n## Address\n\nThe base address for this version of the API, to be used before every endpoint\nlisted here, is:\n\n```\nhttps://api.spoke.com/connect/v1\n```\n\nNotice the `https://` prefix. The Connect API will **not** accept plain HTTP\nrequests.\n\n## Your first request\n\nEvery request must be authenticated with an API key. The following request\nlists your orders:\n\n```bash\ncurl \"https://api.spoke.com/connect/v1/orders\" \\\n -H \"Authorization: Bearer \"\n```\n\nThe response contains an `orders` array, plus a `nextPageToken` cursor to pass\nas `pageToken` when there are more results to fetch.\n\n## Authentication\n\nEvery Connect API request must be authenticated with an API key.\n\n### Creating API keys\n\nAPI keys are created and expired from the **Integrations** page in your Connect\nsettings, by retailer admins. You can have up to 5 active keys at a time.\nExpired keys don't count towards the limit.\n\nTreat your keys as secrets: don't embed them in client-side code, and expire\nany key you suspect has leaked.\n\n### Using your key\n\nPass the key in the `Authorization` header. Both the `Bearer` and `Basic`\nschemes are accepted:\n\n```\nAuthorization: Bearer \n```\n\n```\nAuthorization: Basic :)>\n```\n\nFor `Basic`, use the API key as the username and leave the password empty.\n`curl` builds the encoded header for you with `-u \":\"`:\n\n```bash\ncurl \"https://api.spoke.com/connect/v1/orders\" -u \":\"\n```\n\n### Authentication errors\n\nRequests with a missing, invalid, or expired key are rejected with a\n`401 Unauthorized` response.\n\n## On resource types\n\nEvery response from the Connect API is a JSON object, and every request that\ncarries a body must send it as JSON with the `Content-Type: application/json`\nheader.\n\nThe API exposes four resource types:\n\n| Resource | What it is | Where |\n| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |\n| `Order` | A package, or set of packages, you are sending to a recipient through a courier. Everything else in the API exists to describe or act on an order. | Read and write, `/orders` |\n| `Courier` | A courier your retailer account is connected to, and that you can submit orders to. | Read-only, `/couriers` |\n| `PickupLocation` | One of your own locations a courier can collect from, referenced by an order's `deliveryInstructions.handOffInfo.pickupLocationId`. | Read-only, `/pickupLocations` |\n| `OrderShippingLabels` | A short-lived signed link to an order's printable labels, rendered as a single PDF. | Read-only, `/orders/{id}/shippingLabels` |\n\nCouriers and pickup locations are managed in the Spoke Connect app, not through\nthis API. The API reads them so you can reference them by id when you create\nand submit orders.\n\nWhat every field on these resources means is documented on the\n[Models](/docs/models) pages.\n\n## On resource IDs\n\nEvery resource in the Connect API has a unique id that Spoke generates. Every\nresource representation the API returns shows that id in the following format:\n\n```json\n{\n \"id\": \"collectionName/resourceId\"\n}\n```\n\nSo an order comes back as:\n\n```json\n{\n \"id\": \"orders/W3kJpzQm9q4LV2BdH7sNuT\"\n}\n```\n\nIds are unique per collection, so `orders/...`, `couriers/...`, and\n`pickupLocations/...` name an order, a courier, and a pickup location\nrespectively.\n\nThis means that to act on a resource directly you append its id to the base\naddress exactly as it came back:\n\n```bash\ncurl \"https://api.spoke.com/connect/v1/`serializedId`\" \\\n -H \"Authorization: Bearer \"\n```\n\nFor the order above that is:\n\n```bash\ncurl \"https://api.spoke.com/connect/v1/orders/W3kJpzQm9q4LV2BdH7sNuT\" \\\n -H \"Authorization: Bearer \"\n```\n\nSub-resources hang off the same id, so that order's labels are at\n`orders/W3kJpzQm9q4LV2BdH7sNuT/shippingLabels`.\n\nThe endpoint reference below writes the same paths in OpenAPI template\nnotation, as `/orders/{id}`. That describes the URL you just built, so there is\nno second id format to keep track of.\n\nSend ids back in the form you received them. `courierId` on\n`POST /orders:submit`, and `pickupLocationId` on an order, both take the full\nprefixed value.\n\n## On List endpoints\n\nEvery list endpoint is paginated. One request returns at most one page, and the\nresponse carries a `nextPageToken` you pass back as the `pageToken` query\nparameter to fetch the next one.\n\nPage size is set with `maxPageSize`. Each endpoint has its own default and\nmaximum:\n\n| Endpoint | Default | Maximum |\n| ---------------------- | ------- | ------- |\n| `GET /orders` | 50 | 50 |\n| `GET /couriers` | 100 | 100 |\n| `GET /pickupLocations` | 100 | 100 |\n\nA `maxPageSize` above the maximum is rejected with `400 Bad Request` rather\nthan silently clamped.\n\nWalking a whole collection looks like this:\n\n1. Request the first page. Orders come back newest first.\n\n```bash\ncurl \"https://api.spoke.com/connect/v1/orders?maxPageSize=50\" \\\n -H \"Authorization: Bearer \"\n```\n\n2. The response carries a cursor when more results exist:\n\n```json\n{\n \"orders\": [],\n \"nextPageToken\": \"MTc3ODUwODUwMnxXM2tKcHpRbTlxNExWMkJkSDdzTnVU\"\n}\n```\n\n3. Pass it as `pageToken`, keeping every other query parameter identical to the\n first request:\n\n```bash\ncurl \"https://api.spoke.com/connect/v1/orders?maxPageSize=50&pageToken=MTc3ODUwODUwMnxXM2tKcHpRbTlxNExWMkJkSDdzTnVU\" \\\n -H \"Authorization: Bearer \"\n```\n\n4. Repeat until `nextPageToken` comes back `null`. That is the only signal that\n the collection is exhausted.\n\n**A short page is not the last page.** Every list endpoint filters its page\nafter reading it: `GET /orders` drops deleted and demo orders, and\n`GET /couriers` drops connections whose courier no longer exists. A page can\ntherefore come back with fewer items than `maxPageSize`, or with none at all,\nwhile `nextPageToken` is still set. Stop when `nextPageToken` is `null`, never\nwhen a page looks short.\n\nTokens are opaque, and only the token a list endpoint handed you is meaningful\nto it. Do not parse one, build one, or carry one across walks. `GET /orders`\nrejects a malformed token with `400 Bad Request`. The other list endpoints\nresume from whatever position the token decodes to, so a hand-made one returns\nthe wrong slice rather than an error.\n\n`GET /orders` also accepts an exact-match filter on the order's\n`packageInfo.externalId`, written either as `filter[externalId]=` or\n`filter.externalId=`. External ids are not unique-constrained, so a value you\nhave reused returns every order carrying it.\n\n## On Update endpoints (HTTP PATCH verb)\n\n`PATCH /orders/{id}` is a partial update. What you leave out of the body is\nleft untouched, so you can change one nested field without resending the rest\nof the order.\n\nThree rules cover every field:\n\n- **An omitted field is left unchanged.** An empty nested object (`{}`) is the\n same as omitting it, and a body that sets nothing returns the order\n unchanged.\n- **An explicit `null` clears a nullable field.** Sending\n `{\"deliveryInstructions\": {\"notes\": null}}` removes the notes.\n- **An array replaces the stored array in full.** There is no partial update of\n an array, so send the complete list you want to end up with.\n\nChanging only the delivery notes, for example:\n\n```bash\ncurl -X PATCH \"https://api.spoke.com/connect/v1/orders/W3kJpzQm9q4LV2BdH7sNuT\" \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"deliveryInstructions\": {\"notes\": \"Leave with the neighbour\"}}'\n```\n\nThree exceptions are worth knowing before you write an integration:\n\n- **`address` is replaced, not merged.** An address you send replaces the\n stored address in full and is geocoded again exactly as on create, so it has\n to carry at least one field that can locate the delivery. Sending only `zip`\n discards the street lines rather than amending them.\n- **`deliveryInstructions.handOffInfo.handOffType` cannot be cleared.** It\n accepts `ship_to_courier` or `pickup_by_courier`, and omitting it leaves the\n stored value alone. Once a hand-off type is set there is no way to put the\n order back on your account default. Switching to `ship_to_courier` also\n clears the stored `pickupLocationId`.\n- **Nested objects are never `null` on an edit.** Clear the individual leaves\n instead, for example `{\"deliveryInstructions\": {\"proofOfAttemptRequirements\":\n{\"enabled\": null}}}`.\n\nOnly an editable order can be updated. An order becomes read-only once the\ncourier puts it on a route, and an order the courier added on your behalf\n(`source: \"courier\"`) is read-only from the start. Both answer `409 Conflict`\nwith `code: \"order_read_only\"`.\n\n## On Rate-Limiting\n\nThe Connect API is rate-limited per source IP, at the edge, before a request\nreaches the application. Exceed a limit and the request is rejected with\n`429 Too Many Requests`. That rejection happens ahead of the API, so it carries\nno JSON body: match on the status code, not on an error `code`.\n\nThe limits are:\n\n| Requests | Limit |\n| ---------------------------------- | ------------- |\n| Reads (`GET`) | 10 per second |\n| Writes (`POST`, `PATCH`, `DELETE`) | 5 per second |\n| `POST /orders:import` | 10 per minute |\n| `POST /orders:submit` | 10 per minute |\n\n`:import` and `:submit` are counted in their own separate buckets, and each\nrequest carries up to 100 orders, so each endpoint tops out at 1000 orders per\nminute. That is the reason to prefer the batch endpoints over a loop of\nsingle-resource calls: importing 100 orders spends one request against the\nper-minute budget, where 100 creates spend 100 requests against the\n5-per-second write budget. Every batch endpoint caps the array at 100 and\nrejects a longer one with `400 Bad Request` before processing any item, so size\nyour batches accordingly.\n\nKeep breaching a limit and the ban lengthens: sustained breach over roughly\nthree minutes triggers a temporary block of about twenty minutes, so a client\nthat keeps hammering after a `429` locks itself out for longer than it would\nhave waited. Handle a `429` by backing off instead:\n\n- Wait and retry, using\n [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff).\n- Add a random delay to each attempt, so a fleet of your own workers does not\n retry in lockstep and cause a\n [thundering herd](https://en.wikipedia.org/wiki/Thundering_herd_problem).\n- Do not retry a `4xx` other than `429`. Those describe the request itself, and\n resending it unchanged fails the same way.\n\nRaising a limit is a backwards-compatible change under the\n[versioning policy](/versioning), so the numbers can go up without a new API\nversion. If you have a use case that needs sustained higher throughput, tell us\nabout it before you build it and we will size the limits around it.\n\n## On the models\n\nBelow this section you will find every Connect API endpoint. The resources they\naccept and return are documented field by field on the\n[Models](/docs/models) pages.\n", "version": "v1" }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Pass the API key directly as the token." }, "BasicAuth": { "type": "http", "scheme": "basic", "description": "Use the API key as the username and leave the password empty." } }, "schemas": { "connectCourierIdSchema": { "type": "string", "pattern": "^couriers\\/[a-zA-Z0-9_-]{1,50}$", "description": "Unique identifier of a courier, in the format `couriers/{id}`." }, "connectCourierSchema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/connectCourierIdSchema" } ], "description": "Courier identifier." }, "name": { "type": "string", "description": "The courier's display name." } }, "required": ["id", "name"], "additionalProperties": false, "description": "A courier connected to the retailer." }, "connectOrderBatchResponseSchema": { "type": "object", "properties": { "success": { "type": "array", "items": { "type": "string", "pattern": "^orders\\/[a-zA-Z0-9_-]{1,50}$", "description": "Unique identifier of an order, in the format `orders/{id}`." }, "description": "The ids of the orders created successfully." }, "failed": { "type": "array", "items": { "type": "object", "properties": { "order": { "type": "object", "properties": { "address": { "type": "object", "properties": { "addressLineOne": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "First line of the address." }, "addressLineTwo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Second line of the address." }, "city": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "City." }, "state": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "State." }, "zip": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "Postal code." }, "country": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "Country." }, "addressName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Display-only name for the address. Not used for geocoding." }, "latitude": { "anyOf": [ { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "null" } ], "description": "Latitude in decimal degrees. Overrides the line fields when set." }, "longitude": { "anyOf": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "null" } ], "description": "Longitude in decimal degrees. Overrides the line fields when set." } }, "additionalProperties": false, "description": "Address of the delivery. Every field is optional on its own, but you must provide at least one that can locate the delivery. `addressName` is a display-only label and is never used for geocoding, so it does not count. When `latitude` and `longitude` are set they must be set together and override the other fields for geocoding." }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Full name of the recipient." }, "email": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Email address of the recipient." }, "phone": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Phone number of the recipient." }, "externalId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "The retailer's own id for this recipient in their system." } }, "additionalProperties": false, "description": "Recipient fields accepted when creating or editing an order." }, { "type": "null" } ] }, "packageInfo": { "anyOf": [ { "type": "object", "properties": { "products": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "The products that are part of the order." }, "packageCount": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10000 }, { "type": "null" } ], "description": "The amount of packages in the order. A barcode is created per package. Defaults to 1." }, "packageLoadAmount": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "The amount of the vehicle's load capacity this order takes up. Same unit as the retailer weight setting." }, "externalId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "The retailer's own id for this order in their own system." } }, "additionalProperties": false, "description": "Package details accepted when creating or editing an order." }, { "type": "null" } ] }, "deliveryInstructions": { "anyOf": [ { "type": "object", "properties": { "notes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ], "description": "Notes for the delivery." }, "expectedDeliveryDate": { "anyOf": [ { "type": "object", "properties": { "day": { "type": "integer", "minimum": 1, "maximum": 31, "description": "The day of the date." }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "The month of the date." }, "year": { "type": "integer", "minimum": 2000, "maximum": 2100, "description": "The year of the date." } }, "required": ["day", "month", "year"], "additionalProperties": false, "description": "A date." }, { "type": "null" } ], "description": "Calendar date the retailer expects delivery on. Date-only, in the retailer's local timezone." }, "proofOfAttemptRequirements": { "anyOf": [ { "type": "object", "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the driver must collect proof (signature or photo) on attempt. `null` (or omitted) uses the courier's default." } }, "additionalProperties": false, "description": "Proof-of-attempt fields accepted when creating or editing an order." }, { "type": "null" } ] }, "handOffInfo": { "anyOf": [ { "type": "object", "properties": { "handOffType": { "anyOf": [ { "type": "string", "enum": [ "ship_to_courier", "pickup_by_courier" ], "description": "How an order is handed off to the courier." }, { "type": "null" } ], "description": "The hand-off type. `null` (or omitted) uses the retailer's default." }, "pickupLocationId": { "anyOf": [ { "type": "string", "pattern": "^pickupLocations\\/[a-zA-Z0-9_-]{1,50}$", "description": "Unique identifier of a pickup location, in the format `pickupLocations/{id}`." }, { "type": "null" } ], "description": "The retailer location the courier picks up from. Only applies when `handOffType` is `pickup_by_courier`." } }, "additionalProperties": false, "description": "Hand-off fields accepted when creating or editing an order." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Delivery-instruction fields accepted when creating or editing an order." }, { "type": "null" } ] }, "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The index in the request array, used to correlate the failure with the input." } }, "additionalProperties": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "The public error code." }, "message": { "type": "string", "description": "A human-readable error message." } }, "required": ["code", "message"] } }, "required": ["order", "error"] }, "description": "The inputs that failed, each with the public error code." } }, "required": ["success", "failed"], "additionalProperties": false, "description": "Response shape returned by the batch endpoint `POST /orders:import`." }, "connectOrderCreateRequestSchema": { "type": "object", "properties": { "address": { "type": "object", "properties": { "addressLineOne": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "First line of the address." }, "addressLineTwo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Second line of the address." }, "city": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "City." }, "state": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "State." }, "zip": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "Postal code." }, "country": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "Country." }, "addressName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Display-only name for the address. Not used for geocoding." }, "latitude": { "anyOf": [ { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "null" } ], "description": "Latitude in decimal degrees. Overrides the line fields when set." }, "longitude": { "anyOf": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "null" } ], "description": "Longitude in decimal degrees. Overrides the line fields when set." } }, "additionalProperties": false, "description": "Address of the delivery. Every field is optional on its own, but you must provide at least one that can locate the delivery. `addressName` is a display-only label and is never used for geocoding, so it does not count. When `latitude` and `longitude` are set they must be set together and override the other fields for geocoding." }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Full name of the recipient." }, "email": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Email address of the recipient." }, "phone": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Phone number of the recipient." }, "externalId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "The retailer's own id for this recipient in their system." } }, "additionalProperties": false, "description": "Recipient fields accepted when creating or editing an order." }, { "type": "null" } ] }, "packageInfo": { "anyOf": [ { "type": "object", "properties": { "products": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "The products that are part of the order." }, "packageCount": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10000 }, { "type": "null" } ], "description": "The amount of packages in the order. A barcode is created per package. Defaults to 1." }, "packageLoadAmount": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "The amount of the vehicle's load capacity this order takes up. Same unit as the retailer weight setting." }, "externalId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "The retailer's own id for this order in their own system." } }, "additionalProperties": false, "description": "Package details accepted when creating or editing an order." }, { "type": "null" } ] }, "deliveryInstructions": { "anyOf": [ { "type": "object", "properties": { "notes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ], "description": "Notes for the delivery." }, "expectedDeliveryDate": { "anyOf": [ { "type": "object", "properties": { "day": { "type": "integer", "minimum": 1, "maximum": 31, "description": "The day of the date." }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "The month of the date." }, "year": { "type": "integer", "minimum": 2000, "maximum": 2100, "description": "The year of the date." } }, "required": ["day", "month", "year"], "additionalProperties": false, "description": "A date." }, { "type": "null" } ], "description": "Calendar date the retailer expects delivery on. Date-only, in the retailer's local timezone." }, "proofOfAttemptRequirements": { "anyOf": [ { "type": "object", "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the driver must collect proof (signature or photo) on attempt. `null` (or omitted) uses the courier's default." } }, "additionalProperties": false, "description": "Proof-of-attempt fields accepted when creating or editing an order." }, { "type": "null" } ] }, "handOffInfo": { "anyOf": [ { "type": "object", "properties": { "handOffType": { "anyOf": [ { "type": "string", "enum": [ "ship_to_courier", "pickup_by_courier" ], "description": "How an order is handed off to the courier." }, { "type": "null" } ], "description": "The hand-off type. `null` (or omitted) uses the retailer's default." }, "pickupLocationId": { "anyOf": [ { "type": "string", "pattern": "^pickupLocations\\/[a-zA-Z0-9_-]{1,50}$", "description": "Unique identifier of a pickup location, in the format `pickupLocations/{id}`." }, { "type": "null" } ], "description": "The retailer location the courier picks up from. Only applies when `handOffType` is `pickup_by_courier`." } }, "additionalProperties": false, "description": "Hand-off fields accepted when creating or editing an order." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Delivery-instruction fields accepted when creating or editing an order." }, { "type": "null" } ] } }, "required": ["address"], "additionalProperties": false, "description": "Input shape accepted by `POST /orders` and `POST /orders:import`. Only `address` is required." }, "connectOrderIdBatchResponseSchema": { "type": "object", "properties": { "success": { "type": "array", "items": { "type": "string", "pattern": "^orders\\/[a-zA-Z0-9_-]{1,50}$" }, "description": "The ids of the orders processed successfully." }, "failed": { "type": "array", "items": { "type": "object", "properties": { "orderId": { "type": "string", "pattern": "^orders\\/[a-zA-Z0-9_-]{1,50}$", "description": "The order id the failure applies to." }, "error": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "enum": [ "order_not_found", "order_already_submitted", "order_invalid_fields", "order_concurrent_modification" ] }, { "type": "string" } ], "description": "The public error code." }, "message": { "type": "string", "description": "A human-readable error message." } }, "required": ["code", "message"], "additionalProperties": false, "description": "Why the order was not processed: a stable public code plus a human-readable message." } }, "required": ["orderId", "error"], "additionalProperties": false }, "description": "The order ids that failed, each with the public error code." } }, "required": ["success", "failed"], "additionalProperties": false, "description": "Response shape returned by the batch endpoints that act on existing orders (`POST /orders:submit`). The same envelope as the import batch response, but `failed` echoes the order id being acted on instead of an order body." }, "connectOrderIdSchema": { "type": "string", "pattern": "^orders\\/[a-zA-Z0-9_-]{1,50}$", "description": "Unique identifier of an order, in the format `orders/{id}`." }, "connectOrderImportRequestSchema": { "type": "object", "properties": { "orders": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "address": { "type": "object", "properties": { "addressLineOne": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "First line of the address." }, "addressLineTwo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Second line of the address." }, "city": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "City." }, "state": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "State." }, "zip": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "Postal code." }, "country": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "Country." }, "addressName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Display-only name for the address. Not used for geocoding." }, "latitude": { "anyOf": [ { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "null" } ], "description": "Latitude in decimal degrees. Overrides the line fields when set." }, "longitude": { "anyOf": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "null" } ], "description": "Longitude in decimal degrees. Overrides the line fields when set." } }, "additionalProperties": false, "description": "Address of the delivery. Every field is optional on its own, but you must provide at least one that can locate the delivery. `addressName` is a display-only label and is never used for geocoding, so it does not count. When `latitude` and `longitude` are set they must be set together and override the other fields for geocoding." }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Full name of the recipient." }, "email": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Email address of the recipient." }, "phone": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Phone number of the recipient." }, "externalId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "The retailer's own id for this recipient in their system." } }, "additionalProperties": false, "description": "Recipient fields accepted when creating or editing an order." }, { "type": "null" } ] }, "packageInfo": { "anyOf": [ { "type": "object", "properties": { "products": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "The products that are part of the order." }, "packageCount": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10000 }, { "type": "null" } ], "description": "The amount of packages in the order. A barcode is created per package. Defaults to 1." }, "packageLoadAmount": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "The amount of the vehicle's load capacity this order takes up. Same unit as the retailer weight setting." }, "externalId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "The retailer's own id for this order in their own system." } }, "additionalProperties": false, "description": "Package details accepted when creating or editing an order." }, { "type": "null" } ] }, "deliveryInstructions": { "anyOf": [ { "type": "object", "properties": { "notes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ], "description": "Notes for the delivery." }, "expectedDeliveryDate": { "anyOf": [ { "type": "object", "properties": { "day": { "type": "integer", "minimum": 1, "maximum": 31, "description": "The day of the date." }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "The month of the date." }, "year": { "type": "integer", "minimum": 2000, "maximum": 2100, "description": "The year of the date." } }, "required": ["day", "month", "year"], "additionalProperties": false, "description": "A date." }, { "type": "null" } ], "description": "Calendar date the retailer expects delivery on. Date-only, in the retailer's local timezone." }, "proofOfAttemptRequirements": { "anyOf": [ { "type": "object", "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the driver must collect proof (signature or photo) on attempt. `null` (or omitted) uses the courier's default." } }, "additionalProperties": false, "description": "Proof-of-attempt fields accepted when creating or editing an order." }, { "type": "null" } ] }, "handOffInfo": { "anyOf": [ { "type": "object", "properties": { "handOffType": { "anyOf": [ { "type": "string", "enum": [ "ship_to_courier", "pickup_by_courier" ], "description": "How an order is handed off to the courier." }, { "type": "null" } ], "description": "The hand-off type. `null` (or omitted) uses the retailer's default." }, "pickupLocationId": { "anyOf": [ { "type": "string", "pattern": "^pickupLocations\\/[a-zA-Z0-9_-]{1,50}$", "description": "Unique identifier of a pickup location, in the format `pickupLocations/{id}`." }, { "type": "null" } ], "description": "The retailer location the courier picks up from. Only applies when `handOffType` is `pickup_by_courier`." } }, "additionalProperties": false, "description": "Hand-off fields accepted when creating or editing an order." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Delivery-instruction fields accepted when creating or editing an order." }, { "type": "null" } ] } }, "required": ["address"], "additionalProperties": false, "description": "Input shape accepted by `POST /orders` and `POST /orders:import`. Only `address` is required." }, "description": "The orders to create. At most 100 per request." } }, "required": ["orders"], "additionalProperties": false, "description": "Input shape accepted by `POST /orders:import`." }, "connectOrderListResponseSchema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/connectOrderSchema" }, "description": "The page of orders." }, "nextPageToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque token for the next page. `null` on the last page." } }, "required": ["orders", "nextPageToken"], "additionalProperties": false, "description": "Response shape returned by `GET /orders`." }, "connectOrderSchema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/connectOrderIdSchema" } ], "description": "The order identifier." }, "createdAt": { "type": "number", "description": "Timestamp in seconds when the order was created." }, "recipient": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full name of the recipient." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address of the recipient." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone number of the recipient." }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The retailer's own id for this recipient in their system." } }, "required": ["name", "email", "phone", "externalId"], "additionalProperties": false, "description": "Recipient of the delivery." }, "packageInfo": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "string" }, "description": "The products that are part of the order." }, "packageCount": { "type": "number", "description": "The amount of packages that are part of the order. For every package, a barcode will be created." }, "packageLoadAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The amount of the vehicle's load capacity this order takes up. Same unit as the retailer weight setting." }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The retailer's own id for this order in their own system." } }, "required": [ "products", "packageCount", "packageLoadAmount", "externalId" ], "additionalProperties": false, "description": "Package details: products, quantities, and the retailer's own id for this order." }, "address": { "type": "object", "properties": { "address": { "type": "string", "description": "Combined address string. Computed by geocoding, and empty when the order was created from coordinates only." }, "addressLineOne": { "type": "string", "description": "First line of the address." }, "addressLineTwo": { "type": "string", "description": "Second line of the address." }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Latitude coordinate in decimal degrees." }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Longitude coordinate in decimal degrees." }, "placeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Google Places identifier for this location." }, "placeTypes": { "type": "array", "items": { "type": "string" }, "description": "Place types from the Google Places API." } }, "required": [ "address", "addressLineOne", "addressLineTwo", "latitude", "longitude", "placeId", "placeTypes" ], "additionalProperties": false, "description": "Address of the delivery as returned on an `Order`." }, "deliveryInstructions": { "type": "object", "properties": { "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Notes for the delivery." }, "expectedDeliveryDate": { "anyOf": [ { "type": "object", "properties": { "day": { "type": "integer", "minimum": 1, "maximum": 31, "description": "The day of the date." }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "The month of the date." }, "year": { "type": "integer", "minimum": 2000, "maximum": 2100, "description": "The year of the date." } }, "required": ["day", "month", "year"], "additionalProperties": false }, { "type": "null" } ], "description": "Calendar date the retailer expects delivery on. Date-only, in the retailer's local timezone." }, "proofOfAttemptRequirements": { "type": "object", "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the driver must collect proof (signature or photo) on attempt. `null` uses the courier default, `false` disables it for this order, `true` enables it following the courier per-attempt-type policies." } }, "required": ["enabled"], "additionalProperties": false, "description": "Proof-of-attempt requirements for an order." }, "handOffInfo": { "type": "object", "properties": { "handOffType": { "anyOf": [ { "type": "string", "enum": ["ship_to_courier", "pickup_by_courier"], "description": "How an order is handed off to the courier." }, { "type": "null" } ], "description": "The hand-off type. `ship_to_courier`: the retailer ships to the courier, no pickup. `pickup_by_courier`: the courier picks up from a retailer location. When `null`, the retailer's default applies." }, "pickupLocationId": { "anyOf": [ { "$ref": "#/components/schemas/connectPickupLocationIdSchema" }, { "type": "null" } ], "description": "The retailer location the courier picks up from when `handOffType` is `pickup_by_courier`. Must be `null` when `handOffType` is `ship_to_courier`." } }, "required": ["handOffType", "pickupLocationId"], "additionalProperties": false, "description": "How an order is handed off to the courier." } }, "required": [ "notes", "expectedDeliveryDate", "proofOfAttemptRequirements", "handOffInfo" ], "additionalProperties": false, "description": "How and when an order should be delivered: notes, the expected delivery date, proof-of-attempt requirements, and hand-off details." }, "courier": { "anyOf": [ { "$ref": "#/components/schemas/connectCourierIdSchema" }, { "type": "null" } ], "description": "The courier this order has been submitted to. `null` until the order is submitted." }, "submitted": { "type": "boolean", "description": "Whether the order has been submitted to a courier." }, "submittedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Timestamp in seconds when the order was submitted to a courier." }, "progress": { "anyOf": [ { "type": "object", "properties": { "trackingLink": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tracking link the recipient can follow." }, "eta": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": ["available"] }, "value": { "type": "object", "properties": { "estimatedArrivalAt": { "type": "number", "description": "Estimated arrival, in seconds since epoch." }, "estimatedEarliestArrivalAt": { "type": "number", "description": "Earliest arrival of the window, in seconds since epoch." }, "estimatedLatestArrivalAt": { "type": "number", "description": "Latest arrival of the window, in seconds since epoch." } }, "required": [ "estimatedArrivalAt", "estimatedEarliestArrivalAt", "estimatedLatestArrivalAt" ], "additionalProperties": false, "description": "Estimated time of arrival, with an earliest and latest window." } }, "required": ["status", "value"], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": ["restricted"] }, "restrictionCode": { "type": "string" } }, "required": ["status"], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": ["pending"] }, "pendingReason": { "type": "string" } }, "required": ["status"], "additionalProperties": false } ] }, "attempted": { "type": "boolean", "description": "Whether a delivery attempt has been completed, successful or not." }, "attemptedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Timestamp in seconds of when the driver attempted delivery." }, "state": { "type": "string", "enum": [ "delivered_to_recipient", "delivered_to_third_party", "delivered_to_mailbox", "delivered_to_safe_place", "delivered_to_pickup_point", "delivered_other", "picked_up_from_customer", "picked_up_unmanned", "picked_up_from_locker", "picked_up_other", "failed_not_home", "failed_cant_find_address", "failed_no_parking", "failed_no_time", "failed_package_not_available", "failed_missing_required_proof", "failed_payment_not_received", "failed_other", "unattempted" ], "description": "The current state of the delivery." }, "routeStartDate": { "type": "object", "properties": { "day": { "type": "integer", "minimum": 1, "maximum": 31, "description": "The day of the date." }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "The month of the date." }, "year": { "type": "integer", "minimum": 2000, "maximum": 2100, "description": "The year of the date." } }, "required": ["day", "month", "year"], "additionalProperties": false, "description": "Date the route started or is planned to start." }, "routeStarted": { "type": "boolean", "description": "Whether the route this order is on has been started by the driver." }, "succeeded": { "type": "boolean", "description": "Whether the delivery was successful." }, "photoUrls": { "type": "array", "items": { "type": "string" }, "description": "URLs of proof-of-attempt photos taken by the driver. A URL can return not-found while the driver's app is still uploading the photo." }, "signatureUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL of the captured signature image, when one was collected. Subject to the same upload delay as `photoUrls`." }, "signeeName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the signee, when a signature was collected." }, "driverProvidedRecipientNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Notes provided by the driver for the recipient." } }, "required": [ "trackingLink", "eta", "attempted", "attemptedAt", "state", "routeStartDate", "routeStarted", "succeeded", "photoUrls", "signatureUrl", "signeeName", "driverProvidedRecipientNotes" ], "additionalProperties": false, "description": "Progress for an order: ETA, attempt outcome, and any proof captured on the delivery attempt." }, { "type": "null" } ], "description": "Progress for the order. `null` until the courier assigns the order to a route." }, "readOnly": { "type": "boolean", "description": "Whether the order is read-only. Read-only orders cannot be edited or withdrawn." }, "source": { "type": "string", "enum": ["retailer", "courier"], "description": "Where the order originated. `retailer`: created by the retailer. `courier`: added by the courier on the retailer's behalf, surfaced read-only." }, "barcodes": { "type": "array", "items": { "type": "string" }, "description": "List of barcodes associated with the Order." } }, "required": [ "id", "createdAt", "recipient", "packageInfo", "address", "deliveryInstructions", "courier", "submitted", "submittedAt", "progress", "readOnly", "source", "barcodes" ], "additionalProperties": false, "description": "The Order data model. All orders in the API will have this format." }, "connectOrderShippingLabelsSchema": { "type": "object", "properties": { "url": { "type": "string", "description": "Signed URL to the shipping-labels PDF. Fetchable without the API key until it expires." }, "expiresAt": { "type": "number", "description": "When the signed URL stops working, in seconds since epoch." } }, "required": ["url", "expiresAt"], "additionalProperties": false, "description": "A short-lived link to an order's printable shipping labels." }, "connectOrderSubmitRequestSchema": { "type": "object", "properties": { "orderIds": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "pattern": "^orders\\/[a-zA-Z0-9_-]{1,50}$", "description": "Unique identifier of an order, in the format `orders/{id}`." }, "description": "The orders to submit. At most 100 per request." }, "courierId": { "type": "string", "pattern": "^couriers\\/[a-zA-Z0-9_-]{1,50}$", "description": "The courier to submit the orders to. Must be a courier connected to the retailer." } }, "required": ["orderIds", "courierId"], "additionalProperties": false, "description": "Input shape accepted by `POST /orders:submit`." }, "connectOrderUpdateRequestSchema": { "type": "object", "properties": { "address": { "type": "object", "properties": { "addressLineOne": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "First line of the address." }, "addressLineTwo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Second line of the address." }, "city": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "City." }, "state": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "State." }, "zip": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "Postal code." }, "country": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "Country." }, "addressName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Display-only name for the address. Not used for geocoding." }, "latitude": { "anyOf": [ { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "null" } ], "description": "Latitude in decimal degrees. Overrides the line fields when set." }, "longitude": { "anyOf": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "null" } ], "description": "Longitude in decimal degrees. Overrides the line fields when set." } }, "additionalProperties": false, "description": "Address of the delivery. Every field is optional on its own, but you must provide at least one that can locate the delivery. `addressName` is a display-only label and is never used for geocoding, so it does not count. When `latitude` and `longitude` are set they must be set together and override the other fields for geocoding." }, "recipient": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Full name of the recipient." }, "email": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Email address of the recipient." }, "phone": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Phone number of the recipient." }, "externalId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "The retailer's own id for this recipient in their system." } }, "additionalProperties": false, "description": "Recipient fields accepted when creating or editing an order." }, "packageInfo": { "type": "object", "properties": { "products": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "The products that are part of the order." }, "packageCount": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10000 }, { "type": "null" } ], "description": "The amount of packages in the order. A barcode is created per package. Defaults to 1." }, "packageLoadAmount": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "The amount of the vehicle's load capacity this order takes up. Same unit as the retailer weight setting." }, "externalId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "The retailer's own id for this order in their own system." } }, "additionalProperties": false, "description": "Package details accepted when creating or editing an order." }, "deliveryInstructions": { "type": "object", "properties": { "notes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ], "description": "Notes for the delivery. `null` clears them." }, "expectedDeliveryDate": { "anyOf": [ { "type": "object", "properties": { "day": { "type": "integer", "minimum": 1, "maximum": 31, "description": "The day of the date." }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "The month of the date." }, "year": { "type": "integer", "minimum": 2000, "maximum": 2100, "description": "The year of the date." } }, "required": ["day", "month", "year"], "additionalProperties": false, "description": "A date." }, { "type": "null" } ], "description": "Calendar date the retailer expects delivery on. Date-only, in the retailer's local timezone. `null` clears it." }, "proofOfAttemptRequirements": { "type": "object", "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the driver must collect proof (signature or photo) on attempt. Omitted leaves it unchanged, `null` reverts to the courier's default." } }, "additionalProperties": false, "description": "Proof-of-attempt fields accepted when editing an order." }, "handOffInfo": { "type": "object", "properties": { "handOffType": { "type": "string", "enum": ["ship_to_courier", "pickup_by_courier"], "description": "How an order is handed off to the courier." }, "pickupLocationId": { "anyOf": [ { "type": "string", "pattern": "^pickupLocations\\/[a-zA-Z0-9_-]{1,50}$", "description": "Unique identifier of a pickup location, in the format `pickupLocations/{id}`." }, { "type": "null" } ], "description": "The retailer location the courier picks up from. Only applies when `handOffType` is `pickup_by_courier`. An omitted id keeps the stored location, and `null` clears it: a pickup order without one picks up at the retailer's main location when submitted." } }, "additionalProperties": false, "description": "Hand-off fields accepted when editing an order. Switching to `ship_to_courier` clears the stored pickup location." } }, "additionalProperties": false, "description": "Delivery-instruction fields accepted when editing an order. The nested objects are never `null` on an edit: clear individual leaves instead (for example `proofOfAttemptRequirements: { enabled: null }`)." } }, "additionalProperties": false, "description": "Input shape accepted by `PATCH /orders/{id}`. An omitted field is left unchanged, an explicit `null` clears a nullable field, an empty nested object changes nothing, and arrays replace the whole stored array." }, "connectOrderWithdrawRequestSchema": { "type": "object", "properties": { "orderIds": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "pattern": "^orders\\/[a-zA-Z0-9_-]{1,50}$", "description": "Unique identifier of an order, in the format `orders/{id}`." }, "description": "The orders to withdraw. At most 100 per request." } }, "required": ["orderIds"], "additionalProperties": false, "description": "Input shape accepted by `POST /orders:withdraw`." }, "connectOrderWithdrawResponseSchema": { "type": "object", "properties": { "success": { "type": "array", "items": { "type": "string", "pattern": "^orders\\/[a-zA-Z0-9_-]{1,50}$" }, "description": "The ids of the orders withdrawn successfully." }, "failed": { "type": "array", "items": { "type": "object", "properties": { "orderId": { "type": "string", "pattern": "^orders\\/[a-zA-Z0-9_-]{1,50}$", "description": "The order id the failure applies to." }, "error": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "enum": [ "order_not_submitted", "order_already_scheduled", "order_not_found", "order_no_courier_link", "order_courier_managed", "order_read_only", "order_concurrent_modification" ] }, { "type": "string" } ], "description": "The public error code." }, "message": { "type": "string", "description": "A human-readable error message." } }, "required": ["code", "message"], "additionalProperties": false, "description": "Why the order was not withdrawn: a stable public code plus a human-readable message." } }, "required": ["orderId", "error"], "additionalProperties": false }, "description": "The order ids that failed, each with the public error code." } }, "required": ["success", "failed"], "additionalProperties": false, "description": "Response shape returned by `POST /orders:withdraw`. The same envelope as the submit batch response, with withdrawal-specific failure codes." }, "connectPickupLocationIdSchema": { "type": "string", "pattern": "^pickupLocations\\/[a-zA-Z0-9_-]{1,50}$", "description": "Unique identifier of a pickup location, in the format `pickupLocations/{id}`." }, "connectPickupLocationSchema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/connectPickupLocationIdSchema" } ], "description": "Pickup location identifier." }, "name": { "type": "string", "description": "The location's display name." } }, "required": ["id", "name"], "additionalProperties": false, "description": "A retailer pickup location." } } }, "paths": { "/orders": { "get": { "operationId": "listOrders", "summary": "List orders", "tags": ["Orders"], "description": "List the authenticated retailer's orders, newest first. Supports cursor pagination and an exact-match filter on `packageInfo.externalId`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "in": "query", "name": "pageToken", "required": false, "description": "The page token to continue from." }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 50 }, "in": "query", "name": "maxPageSize", "required": false, "description": "The maximum number of orders to return. Defaults to 50 and is capped at 50." }, { "schema": { "type": "object", "properties": { "externalId": { "description": "Exact-match filter on the order's `packageInfo.externalId`, accepted as `filter[externalId]=` or `filter.externalId=`. Not unique-constrained, so a reused id returns every match.", "type": "string", "minLength": 1, "maxLength": 255 } }, "additionalProperties": false }, "in": "query", "name": "filter", "required": false, "description": "Filters narrowing the orders returned." } ], "responses": { "200": { "description": "A page of the retailer's orders, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/connectOrderSchema" }, "description": "The page of orders." }, "nextPageToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque token for the next page. `null` on the last page." } }, "required": ["orders", "nextPageToken"], "additionalProperties": false, "description": "A page of the retailer's orders, newest first.", "definitions": { "connectOrderSchema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/connectOrderIdSchema" } ], "description": "The order identifier." }, "createdAt": { "type": "number", "description": "Timestamp in seconds when the order was created." }, "recipient": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full name of the recipient." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address of the recipient." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone number of the recipient." }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The retailer's own id for this recipient in their system." } }, "required": ["name", "email", "phone", "externalId"], "additionalProperties": false, "description": "Recipient of the delivery." }, "packageInfo": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "string" }, "description": "The products that are part of the order." }, "packageCount": { "type": "number", "description": "The amount of packages that are part of the order. For every package, a barcode will be created." }, "packageLoadAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The amount of the vehicle's load capacity this order takes up. Same unit as the retailer weight setting." }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The retailer's own id for this order in their own system." } }, "required": [ "products", "packageCount", "packageLoadAmount", "externalId" ], "additionalProperties": false, "description": "Package details: products, quantities, and the retailer's own id for this order." }, "address": { "type": "object", "properties": { "address": { "type": "string", "description": "Combined address string. Computed by geocoding, and empty when the order was created from coordinates only." }, "addressLineOne": { "type": "string", "description": "First line of the address." }, "addressLineTwo": { "type": "string", "description": "Second line of the address." }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Latitude coordinate in decimal degrees." }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Longitude coordinate in decimal degrees." }, "placeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Google Places identifier for this location." }, "placeTypes": { "type": "array", "items": { "type": "string" }, "description": "Place types from the Google Places API." } }, "required": [ "address", "addressLineOne", "addressLineTwo", "latitude", "longitude", "placeId", "placeTypes" ], "additionalProperties": false, "description": "Address of the delivery as returned on an `Order`." }, "deliveryInstructions": { "type": "object", "properties": { "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Notes for the delivery." }, "expectedDeliveryDate": { "anyOf": [ { "type": "object", "properties": { "day": { "type": "integer", "minimum": 1, "maximum": 31, "description": "The day of the date." }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "The month of the date." }, "year": { "type": "integer", "minimum": 2000, "maximum": 2100, "description": "The year of the date." } }, "required": ["day", "month", "year"], "additionalProperties": false }, { "type": "null" } ], "description": "Calendar date the retailer expects delivery on. Date-only, in the retailer's local timezone." }, "proofOfAttemptRequirements": { "type": "object", "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the driver must collect proof (signature or photo) on attempt. `null` uses the courier default, `false` disables it for this order, `true` enables it following the courier per-attempt-type policies." } }, "required": ["enabled"], "additionalProperties": false, "description": "Proof-of-attempt requirements for an order." }, "handOffInfo": { "type": "object", "properties": { "handOffType": { "anyOf": [ { "type": "string", "enum": [ "ship_to_courier", "pickup_by_courier" ], "description": "How an order is handed off to the courier." }, { "type": "null" } ], "description": "The hand-off type. `ship_to_courier`: the retailer ships to the courier, no pickup. `pickup_by_courier`: the courier picks up from a retailer location. When `null`, the retailer's default applies." }, "pickupLocationId": { "anyOf": [ { "$ref": "#/components/schemas/connectPickupLocationIdSchema" }, { "type": "null" } ], "description": "The retailer location the courier picks up from when `handOffType` is `pickup_by_courier`. Must be `null` when `handOffType` is `ship_to_courier`." } }, "required": ["handOffType", "pickupLocationId"], "additionalProperties": false, "description": "How an order is handed off to the courier." } }, "required": [ "notes", "expectedDeliveryDate", "proofOfAttemptRequirements", "handOffInfo" ], "additionalProperties": false, "description": "How and when an order should be delivered: notes, the expected delivery date, proof-of-attempt requirements, and hand-off details." }, "courier": { "anyOf": [ { "$ref": "#/components/schemas/connectCourierIdSchema" }, { "type": "null" } ], "description": "The courier this order has been submitted to. `null` until the order is submitted." }, "submitted": { "type": "boolean", "description": "Whether the order has been submitted to a courier." }, "submittedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Timestamp in seconds when the order was submitted to a courier." }, "progress": { "anyOf": [ { "type": "object", "properties": { "trackingLink": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tracking link the recipient can follow." }, "eta": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": ["available"] }, "value": { "type": "object", "properties": { "estimatedArrivalAt": { "type": "number", "description": "Estimated arrival, in seconds since epoch." }, "estimatedEarliestArrivalAt": { "type": "number", "description": "Earliest arrival of the window, in seconds since epoch." }, "estimatedLatestArrivalAt": { "type": "number", "description": "Latest arrival of the window, in seconds since epoch." } }, "required": [ "estimatedArrivalAt", "estimatedEarliestArrivalAt", "estimatedLatestArrivalAt" ], "additionalProperties": false, "description": "Estimated time of arrival, with an earliest and latest window." } }, "required": ["status", "value"], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": ["restricted"] }, "restrictionCode": { "type": "string" } }, "required": ["status"], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": ["pending"] }, "pendingReason": { "type": "string" } }, "required": ["status"], "additionalProperties": false } ] }, "attempted": { "type": "boolean", "description": "Whether a delivery attempt has been completed, successful or not." }, "attemptedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Timestamp in seconds of when the driver attempted delivery." }, "state": { "type": "string", "enum": [ "delivered_to_recipient", "delivered_to_third_party", "delivered_to_mailbox", "delivered_to_safe_place", "delivered_to_pickup_point", "delivered_other", "picked_up_from_customer", "picked_up_unmanned", "picked_up_from_locker", "picked_up_other", "failed_not_home", "failed_cant_find_address", "failed_no_parking", "failed_no_time", "failed_package_not_available", "failed_missing_required_proof", "failed_payment_not_received", "failed_other", "unattempted" ], "description": "The current state of the delivery." }, "routeStartDate": { "type": "object", "properties": { "day": { "type": "integer", "minimum": 1, "maximum": 31, "description": "The day of the date." }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "The month of the date." }, "year": { "type": "integer", "minimum": 2000, "maximum": 2100, "description": "The year of the date." } }, "required": ["day", "month", "year"], "additionalProperties": false, "description": "Date the route started or is planned to start." }, "routeStarted": { "type": "boolean", "description": "Whether the route this order is on has been started by the driver." }, "succeeded": { "type": "boolean", "description": "Whether the delivery was successful." }, "photoUrls": { "type": "array", "items": { "type": "string" }, "description": "URLs of proof-of-attempt photos taken by the driver. A URL can return not-found while the driver's app is still uploading the photo." }, "signatureUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL of the captured signature image, when one was collected. Subject to the same upload delay as `photoUrls`." }, "signeeName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the signee, when a signature was collected." }, "driverProvidedRecipientNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Notes provided by the driver for the recipient." } }, "required": [ "trackingLink", "eta", "attempted", "attemptedAt", "state", "routeStartDate", "routeStarted", "succeeded", "photoUrls", "signatureUrl", "signeeName", "driverProvidedRecipientNotes" ], "additionalProperties": false, "description": "Progress for an order: ETA, attempt outcome, and any proof captured on the delivery attempt." }, { "type": "null" } ], "description": "Progress for the order. `null` until the courier assigns the order to a route." }, "readOnly": { "type": "boolean", "description": "Whether the order is read-only. Read-only orders cannot be edited or withdrawn." }, "source": { "type": "string", "enum": ["retailer", "courier"], "description": "Where the order originated. `retailer`: created by the retailer. `courier`: added by the courier on the retailer's behalf, surfaced read-only." }, "barcodes": { "type": "array", "items": { "type": "string" }, "description": "List of barcodes associated with the Order." } }, "required": [ "id", "createdAt", "recipient", "packageInfo", "address", "deliveryInstructions", "courier", "submitted", "submittedAt", "progress", "readOnly", "source", "barcodes" ], "additionalProperties": false, "description": "The Order data model. All orders in the API will have this format." }, "connectOrderIdSchema": { "type": "string", "pattern": "^orders\\/[a-zA-Z0-9_-]{1,50}$" }, "connectPickupLocationIdSchema": { "type": "string", "pattern": "^pickupLocations\\/[a-zA-Z0-9_-]{1,50}$", "description": "Unique identifier of a pickup location, in the format `pickupLocations/{id}`." }, "connectCourierIdSchema": { "type": "string", "pattern": "^couriers\\/[a-zA-Z0-9_-]{1,50}$", "description": "Unique identifier of a courier, in the format `couriers/{id}`." } } } } } }, "400": { "description": "Query parameters are invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "Query parameters are invalid" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "Unauthorized" } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "An internal server error occurred" } } } }, "default": { "description": "The default error model", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "The default error model" } } } } } }, "post": { "operationId": "createOrder", "summary": "Create an order", "tags": ["Orders"], "description": "Create a new order for the authenticated retailer.", "requestBody": { "content": { "application/json": { "schema": { "description": "Input shape accepted by `POST /orders` and `POST /orders:import`. Only `address` is required.", "type": "object", "properties": { "address": { "description": "Address of the delivery. Every field is optional on its own, but you must provide at least one that can locate the delivery. `addressName` is a display-only label and is never used for geocoding, so it does not count. When `latitude` and `longitude` are set they must be set together and override the other fields for geocoding.", "type": "object", "properties": { "addressLineOne": { "description": "First line of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "addressLineTwo": { "description": "Second line of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "city": { "description": "City.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "state": { "description": "State.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "zip": { "description": "Postal code.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "country": { "description": "Country.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "addressName": { "description": "Display-only name for the address. Not used for geocoding.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "latitude": { "description": "Latitude in decimal degrees. Overrides the line fields when set.", "anyOf": [ { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "null" } ] }, "longitude": { "description": "Longitude in decimal degrees. Overrides the line fields when set.", "anyOf": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "null" } ] } }, "additionalProperties": false }, "recipient": { "anyOf": [ { "description": "Recipient fields accepted when creating or editing an order.", "type": "object", "properties": { "name": { "description": "Full name of the recipient.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "email": { "description": "Email address of the recipient.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "phone": { "description": "Phone number of the recipient.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "externalId": { "description": "The retailer's own id for this recipient in their system.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "packageInfo": { "anyOf": [ { "description": "Package details accepted when creating or editing an order.", "type": "object", "properties": { "products": { "description": "The products that are part of the order.", "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "packageCount": { "description": "The amount of packages in the order. A barcode is created per package. Defaults to 1.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10000 }, { "type": "null" } ] }, "packageLoadAmount": { "description": "The amount of the vehicle's load capacity this order takes up. Same unit as the retailer weight setting.", "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "externalId": { "description": "The retailer's own id for this order in their own system.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "deliveryInstructions": { "anyOf": [ { "description": "Delivery-instruction fields accepted when creating or editing an order.", "type": "object", "properties": { "notes": { "description": "Notes for the delivery.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "expectedDeliveryDate": { "description": "Calendar date the retailer expects delivery on. Date-only, in the retailer's local timezone.", "anyOf": [ { "description": "A date.", "type": "object", "properties": { "day": { "description": "The day of the date.", "type": "integer", "minimum": 1, "maximum": 31 }, "month": { "description": "The month of the date.", "type": "integer", "minimum": 1, "maximum": 12 }, "year": { "description": "The year of the date.", "type": "integer", "minimum": 2000, "maximum": 2100 } }, "required": ["day", "month", "year"], "additionalProperties": false }, { "type": "null" } ] }, "proofOfAttemptRequirements": { "anyOf": [ { "description": "Proof-of-attempt fields accepted when creating or editing an order.", "type": "object", "properties": { "enabled": { "description": "Whether the driver must collect proof (signature or photo) on attempt. `null` (or omitted) uses the courier's default.", "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "handOffInfo": { "anyOf": [ { "description": "Hand-off fields accepted when creating or editing an order.", "type": "object", "properties": { "handOffType": { "description": "The hand-off type. `null` (or omitted) uses the retailer's default.", "anyOf": [ { "description": "How an order is handed off to the courier.", "type": "string", "enum": [ "ship_to_courier", "pickup_by_courier" ] }, { "type": "null" } ] }, "pickupLocationId": { "description": "The retailer location the courier picks up from. Only applies when `handOffType` is `pickup_by_courier`.", "anyOf": [ { "description": "Unique identifier of a pickup location, in the format `pickupLocations/{id}`.", "type": "string", "pattern": "^pickupLocations\\/[a-zA-Z0-9_-]{1,50}$" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] } }, "required": ["address"], "additionalProperties": false } } }, "required": true, "description": "Input shape accepted by `POST /orders` and `POST /orders:import`. Only `address` is required." }, "responses": { "201": { "description": "The created order.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/connectOrderIdSchema" } ], "description": "The order identifier." }, "createdAt": { "type": "number", "description": "Timestamp in seconds when the order was created." }, "recipient": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full name of the recipient." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address of the recipient." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone number of the recipient." }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The retailer's own id for this recipient in their system." } }, "required": ["name", "email", "phone", "externalId"], "additionalProperties": false, "description": "Recipient of the delivery." }, "packageInfo": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "string" }, "description": "The products that are part of the order." }, "packageCount": { "type": "number", "description": "The amount of packages that are part of the order. For every package, a barcode will be created." }, "packageLoadAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The amount of the vehicle's load capacity this order takes up. Same unit as the retailer weight setting." }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The retailer's own id for this order in their own system." } }, "required": [ "products", "packageCount", "packageLoadAmount", "externalId" ], "additionalProperties": false, "description": "Package details: products, quantities, and the retailer's own id for this order." }, "address": { "type": "object", "properties": { "address": { "type": "string", "description": "Combined address string. Computed by geocoding, and empty when the order was created from coordinates only." }, "addressLineOne": { "type": "string", "description": "First line of the address." }, "addressLineTwo": { "type": "string", "description": "Second line of the address." }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Latitude coordinate in decimal degrees." }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Longitude coordinate in decimal degrees." }, "placeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Google Places identifier for this location." }, "placeTypes": { "type": "array", "items": { "type": "string" }, "description": "Place types from the Google Places API." } }, "required": [ "address", "addressLineOne", "addressLineTwo", "latitude", "longitude", "placeId", "placeTypes" ], "additionalProperties": false, "description": "Address of the delivery as returned on an `Order`." }, "deliveryInstructions": { "type": "object", "properties": { "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Notes for the delivery." }, "expectedDeliveryDate": { "anyOf": [ { "type": "object", "properties": { "day": { "type": "integer", "minimum": 1, "maximum": 31, "description": "The day of the date." }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "The month of the date." }, "year": { "type": "integer", "minimum": 2000, "maximum": 2100, "description": "The year of the date." } }, "required": ["day", "month", "year"], "additionalProperties": false }, { "type": "null" } ], "description": "Calendar date the retailer expects delivery on. Date-only, in the retailer's local timezone." }, "proofOfAttemptRequirements": { "type": "object", "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the driver must collect proof (signature or photo) on attempt. `null` uses the courier default, `false` disables it for this order, `true` enables it following the courier per-attempt-type policies." } }, "required": ["enabled"], "additionalProperties": false, "description": "Proof-of-attempt requirements for an order." }, "handOffInfo": { "type": "object", "properties": { "handOffType": { "anyOf": [ { "type": "string", "enum": [ "ship_to_courier", "pickup_by_courier" ], "description": "How an order is handed off to the courier." }, { "type": "null" } ], "description": "The hand-off type. `ship_to_courier`: the retailer ships to the courier, no pickup. `pickup_by_courier`: the courier picks up from a retailer location. When `null`, the retailer's default applies." }, "pickupLocationId": { "anyOf": [ { "$ref": "#/components/schemas/connectPickupLocationIdSchema" }, { "type": "null" } ], "description": "The retailer location the courier picks up from when `handOffType` is `pickup_by_courier`. Must be `null` when `handOffType` is `ship_to_courier`." } }, "required": ["handOffType", "pickupLocationId"], "additionalProperties": false, "description": "How an order is handed off to the courier." } }, "required": [ "notes", "expectedDeliveryDate", "proofOfAttemptRequirements", "handOffInfo" ], "additionalProperties": false, "description": "How and when an order should be delivered: notes, the expected delivery date, proof-of-attempt requirements, and hand-off details." }, "courier": { "anyOf": [ { "$ref": "#/components/schemas/connectCourierIdSchema" }, { "type": "null" } ], "description": "The courier this order has been submitted to. `null` until the order is submitted." }, "submitted": { "type": "boolean", "description": "Whether the order has been submitted to a courier." }, "submittedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Timestamp in seconds when the order was submitted to a courier." }, "progress": { "anyOf": [ { "type": "object", "properties": { "trackingLink": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tracking link the recipient can follow." }, "eta": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": ["available"] }, "value": { "type": "object", "properties": { "estimatedArrivalAt": { "type": "number", "description": "Estimated arrival, in seconds since epoch." }, "estimatedEarliestArrivalAt": { "type": "number", "description": "Earliest arrival of the window, in seconds since epoch." }, "estimatedLatestArrivalAt": { "type": "number", "description": "Latest arrival of the window, in seconds since epoch." } }, "required": [ "estimatedArrivalAt", "estimatedEarliestArrivalAt", "estimatedLatestArrivalAt" ], "additionalProperties": false, "description": "Estimated time of arrival, with an earliest and latest window." } }, "required": ["status", "value"], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": ["restricted"] }, "restrictionCode": { "type": "string" } }, "required": ["status"], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": ["pending"] }, "pendingReason": { "type": "string" } }, "required": ["status"], "additionalProperties": false } ] }, "attempted": { "type": "boolean", "description": "Whether a delivery attempt has been completed, successful or not." }, "attemptedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Timestamp in seconds of when the driver attempted delivery." }, "state": { "type": "string", "enum": [ "delivered_to_recipient", "delivered_to_third_party", "delivered_to_mailbox", "delivered_to_safe_place", "delivered_to_pickup_point", "delivered_other", "picked_up_from_customer", "picked_up_unmanned", "picked_up_from_locker", "picked_up_other", "failed_not_home", "failed_cant_find_address", "failed_no_parking", "failed_no_time", "failed_package_not_available", "failed_missing_required_proof", "failed_payment_not_received", "failed_other", "unattempted" ], "description": "The current state of the delivery." }, "routeStartDate": { "type": "object", "properties": { "day": { "type": "integer", "minimum": 1, "maximum": 31, "description": "The day of the date." }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "The month of the date." }, "year": { "type": "integer", "minimum": 2000, "maximum": 2100, "description": "The year of the date." } }, "required": ["day", "month", "year"], "additionalProperties": false, "description": "Date the route started or is planned to start." }, "routeStarted": { "type": "boolean", "description": "Whether the route this order is on has been started by the driver." }, "succeeded": { "type": "boolean", "description": "Whether the delivery was successful." }, "photoUrls": { "type": "array", "items": { "type": "string" }, "description": "URLs of proof-of-attempt photos taken by the driver. A URL can return not-found while the driver's app is still uploading the photo." }, "signatureUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL of the captured signature image, when one was collected. Subject to the same upload delay as `photoUrls`." }, "signeeName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the signee, when a signature was collected." }, "driverProvidedRecipientNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Notes provided by the driver for the recipient." } }, "required": [ "trackingLink", "eta", "attempted", "attemptedAt", "state", "routeStartDate", "routeStarted", "succeeded", "photoUrls", "signatureUrl", "signeeName", "driverProvidedRecipientNotes" ], "additionalProperties": false, "description": "Progress for an order: ETA, attempt outcome, and any proof captured on the delivery attempt." }, { "type": "null" } ], "description": "Progress for the order. `null` until the courier assigns the order to a route." }, "readOnly": { "type": "boolean", "description": "Whether the order is read-only. Read-only orders cannot be edited or withdrawn." }, "source": { "type": "string", "enum": ["retailer", "courier"], "description": "Where the order originated. `retailer`: created by the retailer. `courier`: added by the courier on the retailer's behalf, surfaced read-only." }, "barcodes": { "type": "array", "items": { "type": "string" }, "description": "List of barcodes associated with the Order." } }, "required": [ "id", "createdAt", "recipient", "packageInfo", "address", "deliveryInstructions", "courier", "submitted", "submittedAt", "progress", "readOnly", "source", "barcodes" ], "additionalProperties": false, "description": "The created order.", "definitions": { "connectOrderIdSchema": { "type": "string", "pattern": "^orders\\/[a-zA-Z0-9_-]{1,50}$" }, "connectPickupLocationIdSchema": { "type": "string", "pattern": "^pickupLocations\\/[a-zA-Z0-9_-]{1,50}$", "description": "Unique identifier of a pickup location, in the format `pickupLocations/{id}`." }, "connectCourierIdSchema": { "type": "string", "pattern": "^couriers\\/[a-zA-Z0-9_-]{1,50}$", "description": "Unique identifier of a courier, in the format `couriers/{id}`." } } } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "The request is invalid." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "Unauthorized" } } } }, "422": { "description": "The order could not be processed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "enum": [ "order_address_unresolvable", "order_invalid_fields" ] }, "param": { "type": "string", "description": "The parameter that caused the error." } }, "required": ["message", "code"], "description": "The order could not be processed." } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "An internal server error occurred" } } } }, "default": { "description": "The default error model", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "The default error model" } } } } } } }, "/orders:import": { "post": { "operationId": "importOrders", "summary": "Batch import orders", "tags": ["Orders"], "description": "Create up to 100 orders for the authenticated retailer in one request. Always returns `200`; per-item outcomes are split across `success` and `failed`.", "requestBody": { "content": { "application/json": { "schema": { "description": "Input shape accepted by `POST /orders:import`.", "type": "object", "properties": { "orders": { "description": "The orders to create. At most 100 per request.", "minItems": 1, "maxItems": 100, "type": "array", "items": { "description": "Input shape accepted by `POST /orders` and `POST /orders:import`. Only `address` is required.", "type": "object", "properties": { "address": { "description": "Address of the delivery. Every field is optional on its own, but you must provide at least one that can locate the delivery. `addressName` is a display-only label and is never used for geocoding, so it does not count. When `latitude` and `longitude` are set they must be set together and override the other fields for geocoding.", "type": "object", "properties": { "addressLineOne": { "description": "First line of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "addressLineTwo": { "description": "Second line of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "city": { "description": "City.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "state": { "description": "State.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "zip": { "description": "Postal code.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "country": { "description": "Country.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "addressName": { "description": "Display-only name for the address. Not used for geocoding.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "latitude": { "description": "Latitude in decimal degrees. Overrides the line fields when set.", "anyOf": [ { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "null" } ] }, "longitude": { "description": "Longitude in decimal degrees. Overrides the line fields when set.", "anyOf": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "null" } ] } }, "additionalProperties": false }, "recipient": { "anyOf": [ { "description": "Recipient fields accepted when creating or editing an order.", "type": "object", "properties": { "name": { "description": "Full name of the recipient.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "email": { "description": "Email address of the recipient.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "phone": { "description": "Phone number of the recipient.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "externalId": { "description": "The retailer's own id for this recipient in their system.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "packageInfo": { "anyOf": [ { "description": "Package details accepted when creating or editing an order.", "type": "object", "properties": { "products": { "description": "The products that are part of the order.", "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "packageCount": { "description": "The amount of packages in the order. A barcode is created per package. Defaults to 1.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10000 }, { "type": "null" } ] }, "packageLoadAmount": { "description": "The amount of the vehicle's load capacity this order takes up. Same unit as the retailer weight setting.", "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "externalId": { "description": "The retailer's own id for this order in their own system.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "deliveryInstructions": { "anyOf": [ { "description": "Delivery-instruction fields accepted when creating or editing an order.", "type": "object", "properties": { "notes": { "description": "Notes for the delivery.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "expectedDeliveryDate": { "description": "Calendar date the retailer expects delivery on. Date-only, in the retailer's local timezone.", "anyOf": [ { "description": "A date.", "type": "object", "properties": { "day": { "description": "The day of the date.", "type": "integer", "minimum": 1, "maximum": 31 }, "month": { "description": "The month of the date.", "type": "integer", "minimum": 1, "maximum": 12 }, "year": { "description": "The year of the date.", "type": "integer", "minimum": 2000, "maximum": 2100 } }, "required": ["day", "month", "year"], "additionalProperties": false }, { "type": "null" } ] }, "proofOfAttemptRequirements": { "anyOf": [ { "description": "Proof-of-attempt fields accepted when creating or editing an order.", "type": "object", "properties": { "enabled": { "description": "Whether the driver must collect proof (signature or photo) on attempt. `null` (or omitted) uses the courier's default.", "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "handOffInfo": { "anyOf": [ { "description": "Hand-off fields accepted when creating or editing an order.", "type": "object", "properties": { "handOffType": { "description": "The hand-off type. `null` (or omitted) uses the retailer's default.", "anyOf": [ { "description": "How an order is handed off to the courier.", "type": "string", "enum": [ "ship_to_courier", "pickup_by_courier" ] }, { "type": "null" } ] }, "pickupLocationId": { "description": "The retailer location the courier picks up from. Only applies when `handOffType` is `pickup_by_courier`.", "anyOf": [ { "description": "Unique identifier of a pickup location, in the format `pickupLocations/{id}`.", "type": "string", "pattern": "^pickupLocations\\/[a-zA-Z0-9_-]{1,50}$" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] } }, "required": ["address"], "additionalProperties": false } } }, "required": ["orders"], "additionalProperties": false } } }, "required": true, "description": "Input shape accepted by `POST /orders:import`." }, "responses": { "200": { "description": "The per-item results. Always returned when the request itself is valid, even when every order fails.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "array", "items": { "type": "string", "pattern": "^orders\\/[a-zA-Z0-9_-]{1,50}$", "description": "Unique identifier of an order, in the format `orders/{id}`." }, "description": "The ids of the orders created successfully." }, "failed": { "type": "array", "items": { "type": "object", "properties": { "order": { "type": "object", "properties": { "address": { "type": "object", "properties": { "addressLineOne": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "First line of the address." }, "addressLineTwo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Second line of the address." }, "city": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "City." }, "state": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "State." }, "zip": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "Postal code." }, "country": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "Country." }, "addressName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Display-only name for the address. Not used for geocoding." }, "latitude": { "anyOf": [ { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "null" } ], "description": "Latitude in decimal degrees. Overrides the line fields when set." }, "longitude": { "anyOf": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "null" } ], "description": "Longitude in decimal degrees. Overrides the line fields when set." } }, "additionalProperties": false, "description": "Address of the delivery. Every field is optional on its own, but you must provide at least one that can locate the delivery. `addressName` is a display-only label and is never used for geocoding, so it does not count. When `latitude` and `longitude` are set they must be set together and override the other fields for geocoding." }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Full name of the recipient." }, "email": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Email address of the recipient." }, "phone": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Phone number of the recipient." }, "externalId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "The retailer's own id for this recipient in their system." } }, "additionalProperties": false, "description": "Recipient fields accepted when creating or editing an order." }, { "type": "null" } ] }, "packageInfo": { "anyOf": [ { "type": "object", "properties": { "products": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "The products that are part of the order." }, "packageCount": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10000 }, { "type": "null" } ], "description": "The amount of packages in the order. A barcode is created per package. Defaults to 1." }, "packageLoadAmount": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "The amount of the vehicle's load capacity this order takes up. Same unit as the retailer weight setting." }, "externalId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "The retailer's own id for this order in their own system." } }, "additionalProperties": false, "description": "Package details accepted when creating or editing an order." }, { "type": "null" } ] }, "deliveryInstructions": { "anyOf": [ { "type": "object", "properties": { "notes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ], "description": "Notes for the delivery." }, "expectedDeliveryDate": { "anyOf": [ { "type": "object", "properties": { "day": { "type": "integer", "minimum": 1, "maximum": 31, "description": "The day of the date." }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "The month of the date." }, "year": { "type": "integer", "minimum": 2000, "maximum": 2100, "description": "The year of the date." } }, "required": [ "day", "month", "year" ], "additionalProperties": false, "description": "A date." }, { "type": "null" } ], "description": "Calendar date the retailer expects delivery on. Date-only, in the retailer's local timezone." }, "proofOfAttemptRequirements": { "anyOf": [ { "type": "object", "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the driver must collect proof (signature or photo) on attempt. `null` (or omitted) uses the courier's default." } }, "additionalProperties": false, "description": "Proof-of-attempt fields accepted when creating or editing an order." }, { "type": "null" } ] }, "handOffInfo": { "anyOf": [ { "type": "object", "properties": { "handOffType": { "anyOf": [ { "type": "string", "enum": [ "ship_to_courier", "pickup_by_courier" ], "description": "How an order is handed off to the courier." }, { "type": "null" } ], "description": "The hand-off type. `null` (or omitted) uses the retailer's default." }, "pickupLocationId": { "anyOf": [ { "type": "string", "pattern": "^pickupLocations\\/[a-zA-Z0-9_-]{1,50}$", "description": "Unique identifier of a pickup location, in the format `pickupLocations/{id}`." }, { "type": "null" } ], "description": "The retailer location the courier picks up from. Only applies when `handOffType` is `pickup_by_courier`." } }, "additionalProperties": false, "description": "Hand-off fields accepted when creating or editing an order." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Delivery-instruction fields accepted when creating or editing an order." }, { "type": "null" } ] }, "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The index in the request array, used to correlate the failure with the input." } }, "additionalProperties": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "The public error code." }, "message": { "type": "string", "description": "A human-readable error message." } }, "required": ["code", "message"] } }, "required": ["order", "error"] }, "description": "The inputs that failed, each with the public error code." } }, "required": ["success", "failed"], "additionalProperties": false, "description": "The per-item results. Always returned when the request itself is valid, even when every order fails." } } } }, "400": { "description": "The request is invalid, for example more than 100 orders.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "The request is invalid, for example more than 100 orders." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "Unauthorized" } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "An internal server error occurred" } } } }, "default": { "description": "The default error model", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "The default error model" } } } } } } }, "/orders:submit": { "post": { "operationId": "submitOrders", "summary": "Batch submit orders", "tags": ["Orders"], "description": "Submit up to 100 draft orders to a connected courier in one request. Submitted orders are picked up at the pickup location (or shipped to the courier) and delivered from the courier's depot. Always returns `200` when the courier is valid; per-order outcomes are split across `success` and `failed`.", "requestBody": { "content": { "application/json": { "schema": { "description": "Input shape accepted by `POST /orders:submit`.", "type": "object", "properties": { "orderIds": { "description": "The orders to submit. At most 100 per request.", "minItems": 1, "maxItems": 100, "type": "array", "items": { "description": "Unique identifier of an order, in the format `orders/{id}`.", "type": "string", "pattern": "^orders\\/[a-zA-Z0-9_-]{1,50}$" } }, "courierId": { "description": "The courier to submit the orders to. Must be a courier connected to the retailer.", "type": "string", "pattern": "^couriers\\/[a-zA-Z0-9_-]{1,50}$" } }, "required": ["orderIds", "courierId"], "additionalProperties": false } } }, "required": true, "description": "Input shape accepted by `POST /orders:submit`." }, "responses": { "200": { "description": "The per-order results. Always returned when the request itself is valid, even when every order fails.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "array", "items": { "type": "string", "pattern": "^orders\\/[a-zA-Z0-9_-]{1,50}$" }, "description": "The ids of the orders processed successfully." }, "failed": { "type": "array", "items": { "type": "object", "properties": { "orderId": { "type": "string", "pattern": "^orders\\/[a-zA-Z0-9_-]{1,50}$", "description": "The order id the failure applies to." }, "error": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "enum": [ "order_not_found", "order_already_submitted", "order_invalid_fields", "order_concurrent_modification" ] }, { "type": "string" } ], "description": "The public error code." }, "message": { "type": "string", "description": "A human-readable error message." } }, "required": ["code", "message"], "additionalProperties": false, "description": "Why the order was not processed: a stable public code plus a human-readable message." } }, "required": ["orderId", "error"], "additionalProperties": false }, "description": "The order ids that failed, each with the public error code." } }, "required": ["success", "failed"], "additionalProperties": false, "description": "The per-order results. Always returned when the request itself is valid, even when every order fails." } } } }, "400": { "description": "The request is invalid, for example more than 100 orders.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "The request is invalid, for example more than 100 orders." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "Unauthorized" } } } }, "422": { "description": "The courier cannot be submitted to: no connected courier matches `courierId` (`order_invalid_fields`), or the courier charges per order (`order_courier_requires_payment`) and orders for it are submitted through the Spoke Connect app instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "anyOf": [ { "type": "string", "enum": [ "order_invalid_fields", "order_courier_requires_payment" ] }, { "type": "string" } ] }, "param": { "type": "string", "description": "The parameter that caused the error." } }, "required": ["message", "code"], "description": "The courier cannot be submitted to: no connected courier matches `courierId` (`order_invalid_fields`), or the courier charges per order (`order_courier_requires_payment`) and orders for it are submitted through the Spoke Connect app instead.", "title": "Orders not submittable" } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "An internal server error occurred" } } } }, "default": { "description": "The default error model", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "The default error model" } } } } } } }, "/orders:withdraw": { "post": { "operationId": "withdrawOrders", "summary": "Batch withdraw orders", "tags": ["Orders"], "description": "Withdraw up to 100 submitted orders back to draft in one request. An order that has already been added to a route can no longer be withdrawn. Always returns `200`; per-order outcomes are split across `success` and `failed`.", "requestBody": { "content": { "application/json": { "schema": { "description": "Input shape accepted by `POST /orders:withdraw`.", "type": "object", "properties": { "orderIds": { "description": "The orders to withdraw. At most 100 per request.", "minItems": 1, "maxItems": 100, "type": "array", "items": { "description": "Unique identifier of an order, in the format `orders/{id}`.", "type": "string", "pattern": "^orders\\/[a-zA-Z0-9_-]{1,50}$" } } }, "required": ["orderIds"], "additionalProperties": false } } }, "required": true, "description": "Input shape accepted by `POST /orders:withdraw`." }, "responses": { "200": { "description": "The per-order results. Always returned when the request itself is valid, even when every order fails.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "array", "items": { "type": "string", "pattern": "^orders\\/[a-zA-Z0-9_-]{1,50}$" }, "description": "The ids of the orders withdrawn successfully." }, "failed": { "type": "array", "items": { "type": "object", "properties": { "orderId": { "type": "string", "pattern": "^orders\\/[a-zA-Z0-9_-]{1,50}$", "description": "The order id the failure applies to." }, "error": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "enum": [ "order_not_submitted", "order_already_scheduled", "order_not_found", "order_no_courier_link", "order_courier_managed", "order_read_only", "order_concurrent_modification" ] }, { "type": "string" } ], "description": "The public error code." }, "message": { "type": "string", "description": "A human-readable error message." } }, "required": ["code", "message"], "additionalProperties": false, "description": "Why the order was not withdrawn: a stable public code plus a human-readable message." } }, "required": ["orderId", "error"], "additionalProperties": false }, "description": "The order ids that failed, each with the public error code." } }, "required": ["success", "failed"], "additionalProperties": false, "description": "The per-order results. Always returned when the request itself is valid, even when every order fails." } } } }, "400": { "description": "The request is invalid, for example more than 100 orders.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "The request is invalid, for example more than 100 orders." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "Unauthorized" } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "An internal server error occurred" } } } }, "default": { "description": "The default error model", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "The default error model" } } } } } } }, "/orders/{id}": { "get": { "operationId": "getOrder", "summary": "Retrieve an order", "tags": ["Orders"], "description": "Retrieve a single order for the authenticated retailer.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[a-zA-Z0-9_-]{1,50}$" }, "in": "path", "name": "id", "required": true, "description": "The order id." } ], "responses": { "200": { "description": "The requested order.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/connectOrderIdSchema" } ], "description": "The order identifier." }, "createdAt": { "type": "number", "description": "Timestamp in seconds when the order was created." }, "recipient": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full name of the recipient." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address of the recipient." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone number of the recipient." }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The retailer's own id for this recipient in their system." } }, "required": ["name", "email", "phone", "externalId"], "additionalProperties": false, "description": "Recipient of the delivery." }, "packageInfo": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "string" }, "description": "The products that are part of the order." }, "packageCount": { "type": "number", "description": "The amount of packages that are part of the order. For every package, a barcode will be created." }, "packageLoadAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The amount of the vehicle's load capacity this order takes up. Same unit as the retailer weight setting." }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The retailer's own id for this order in their own system." } }, "required": [ "products", "packageCount", "packageLoadAmount", "externalId" ], "additionalProperties": false, "description": "Package details: products, quantities, and the retailer's own id for this order." }, "address": { "type": "object", "properties": { "address": { "type": "string", "description": "Combined address string. Computed by geocoding, and empty when the order was created from coordinates only." }, "addressLineOne": { "type": "string", "description": "First line of the address." }, "addressLineTwo": { "type": "string", "description": "Second line of the address." }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Latitude coordinate in decimal degrees." }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Longitude coordinate in decimal degrees." }, "placeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Google Places identifier for this location." }, "placeTypes": { "type": "array", "items": { "type": "string" }, "description": "Place types from the Google Places API." } }, "required": [ "address", "addressLineOne", "addressLineTwo", "latitude", "longitude", "placeId", "placeTypes" ], "additionalProperties": false, "description": "Address of the delivery as returned on an `Order`." }, "deliveryInstructions": { "type": "object", "properties": { "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Notes for the delivery." }, "expectedDeliveryDate": { "anyOf": [ { "type": "object", "properties": { "day": { "type": "integer", "minimum": 1, "maximum": 31, "description": "The day of the date." }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "The month of the date." }, "year": { "type": "integer", "minimum": 2000, "maximum": 2100, "description": "The year of the date." } }, "required": ["day", "month", "year"], "additionalProperties": false }, { "type": "null" } ], "description": "Calendar date the retailer expects delivery on. Date-only, in the retailer's local timezone." }, "proofOfAttemptRequirements": { "type": "object", "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the driver must collect proof (signature or photo) on attempt. `null` uses the courier default, `false` disables it for this order, `true` enables it following the courier per-attempt-type policies." } }, "required": ["enabled"], "additionalProperties": false, "description": "Proof-of-attempt requirements for an order." }, "handOffInfo": { "type": "object", "properties": { "handOffType": { "anyOf": [ { "type": "string", "enum": [ "ship_to_courier", "pickup_by_courier" ], "description": "How an order is handed off to the courier." }, { "type": "null" } ], "description": "The hand-off type. `ship_to_courier`: the retailer ships to the courier, no pickup. `pickup_by_courier`: the courier picks up from a retailer location. When `null`, the retailer's default applies." }, "pickupLocationId": { "anyOf": [ { "$ref": "#/components/schemas/connectPickupLocationIdSchema" }, { "type": "null" } ], "description": "The retailer location the courier picks up from when `handOffType` is `pickup_by_courier`. Must be `null` when `handOffType` is `ship_to_courier`." } }, "required": ["handOffType", "pickupLocationId"], "additionalProperties": false, "description": "How an order is handed off to the courier." } }, "required": [ "notes", "expectedDeliveryDate", "proofOfAttemptRequirements", "handOffInfo" ], "additionalProperties": false, "description": "How and when an order should be delivered: notes, the expected delivery date, proof-of-attempt requirements, and hand-off details." }, "courier": { "anyOf": [ { "$ref": "#/components/schemas/connectCourierIdSchema" }, { "type": "null" } ], "description": "The courier this order has been submitted to. `null` until the order is submitted." }, "submitted": { "type": "boolean", "description": "Whether the order has been submitted to a courier." }, "submittedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Timestamp in seconds when the order was submitted to a courier." }, "progress": { "anyOf": [ { "type": "object", "properties": { "trackingLink": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tracking link the recipient can follow." }, "eta": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": ["available"] }, "value": { "type": "object", "properties": { "estimatedArrivalAt": { "type": "number", "description": "Estimated arrival, in seconds since epoch." }, "estimatedEarliestArrivalAt": { "type": "number", "description": "Earliest arrival of the window, in seconds since epoch." }, "estimatedLatestArrivalAt": { "type": "number", "description": "Latest arrival of the window, in seconds since epoch." } }, "required": [ "estimatedArrivalAt", "estimatedEarliestArrivalAt", "estimatedLatestArrivalAt" ], "additionalProperties": false, "description": "Estimated time of arrival, with an earliest and latest window." } }, "required": ["status", "value"], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": ["restricted"] }, "restrictionCode": { "type": "string" } }, "required": ["status"], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": ["pending"] }, "pendingReason": { "type": "string" } }, "required": ["status"], "additionalProperties": false } ] }, "attempted": { "type": "boolean", "description": "Whether a delivery attempt has been completed, successful or not." }, "attemptedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Timestamp in seconds of when the driver attempted delivery." }, "state": { "type": "string", "enum": [ "delivered_to_recipient", "delivered_to_third_party", "delivered_to_mailbox", "delivered_to_safe_place", "delivered_to_pickup_point", "delivered_other", "picked_up_from_customer", "picked_up_unmanned", "picked_up_from_locker", "picked_up_other", "failed_not_home", "failed_cant_find_address", "failed_no_parking", "failed_no_time", "failed_package_not_available", "failed_missing_required_proof", "failed_payment_not_received", "failed_other", "unattempted" ], "description": "The current state of the delivery." }, "routeStartDate": { "type": "object", "properties": { "day": { "type": "integer", "minimum": 1, "maximum": 31, "description": "The day of the date." }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "The month of the date." }, "year": { "type": "integer", "minimum": 2000, "maximum": 2100, "description": "The year of the date." } }, "required": ["day", "month", "year"], "additionalProperties": false, "description": "Date the route started or is planned to start." }, "routeStarted": { "type": "boolean", "description": "Whether the route this order is on has been started by the driver." }, "succeeded": { "type": "boolean", "description": "Whether the delivery was successful." }, "photoUrls": { "type": "array", "items": { "type": "string" }, "description": "URLs of proof-of-attempt photos taken by the driver. A URL can return not-found while the driver's app is still uploading the photo." }, "signatureUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL of the captured signature image, when one was collected. Subject to the same upload delay as `photoUrls`." }, "signeeName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the signee, when a signature was collected." }, "driverProvidedRecipientNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Notes provided by the driver for the recipient." } }, "required": [ "trackingLink", "eta", "attempted", "attemptedAt", "state", "routeStartDate", "routeStarted", "succeeded", "photoUrls", "signatureUrl", "signeeName", "driverProvidedRecipientNotes" ], "additionalProperties": false, "description": "Progress for an order: ETA, attempt outcome, and any proof captured on the delivery attempt." }, { "type": "null" } ], "description": "Progress for the order. `null` until the courier assigns the order to a route." }, "readOnly": { "type": "boolean", "description": "Whether the order is read-only. Read-only orders cannot be edited or withdrawn." }, "source": { "type": "string", "enum": ["retailer", "courier"], "description": "Where the order originated. `retailer`: created by the retailer. `courier`: added by the courier on the retailer's behalf, surfaced read-only." }, "barcodes": { "type": "array", "items": { "type": "string" }, "description": "List of barcodes associated with the Order." } }, "required": [ "id", "createdAt", "recipient", "packageInfo", "address", "deliveryInstructions", "courier", "submitted", "submittedAt", "progress", "readOnly", "source", "barcodes" ], "additionalProperties": false, "description": "The requested order.", "definitions": { "connectOrderIdSchema": { "type": "string", "pattern": "^orders\\/[a-zA-Z0-9_-]{1,50}$" }, "connectPickupLocationIdSchema": { "type": "string", "pattern": "^pickupLocations\\/[a-zA-Z0-9_-]{1,50}$", "description": "Unique identifier of a pickup location, in the format `pickupLocations/{id}`." }, "connectCourierIdSchema": { "type": "string", "pattern": "^couriers\\/[a-zA-Z0-9_-]{1,50}$", "description": "Unique identifier of a courier, in the format `couriers/{id}`." } } } } } }, "400": { "description": "ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "ID format is invalid", "title": "The request is invalid" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "Unauthorized" } } } }, "404": { "description": "The order does not exist, or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "enum": ["order_not_found"] } }, "required": ["message", "code"], "description": "The order does not exist, or has been deleted.", "title": "Order not found" } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "An internal server error occurred" } } } }, "default": { "description": "The default error model", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "The default error model" } } } } } }, "patch": { "operationId": "updateOrder", "summary": "Edit an order", "tags": ["Orders"], "description": "Edit an order for the authenticated retailer. An omitted field is left unchanged, an explicit `null` clears a nullable field, an empty nested object changes nothing, and arrays replace the whole stored array. A provided address replaces the stored address in full and is re-geocoded exactly as on create. A read-only order (added by the courier, or already on a route) cannot be edited.", "requestBody": { "content": { "application/json": { "schema": { "description": "Input shape accepted by `PATCH /orders/{id}`. An omitted field is left unchanged, an explicit `null` clears a nullable field, an empty nested object changes nothing, and arrays replace the whole stored array.", "type": "object", "properties": { "address": { "description": "The address of the delivery. A provided address replaces the stored address in full and is re-geocoded exactly as on create.", "type": "object", "properties": { "addressLineOne": { "description": "First line of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "addressLineTwo": { "description": "Second line of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "city": { "description": "City.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "state": { "description": "State.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "zip": { "description": "Postal code.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "country": { "description": "Country.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "addressName": { "description": "Display-only name for the address. Not used for geocoding.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "latitude": { "description": "Latitude in decimal degrees. Overrides the line fields when set.", "anyOf": [ { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "null" } ] }, "longitude": { "description": "Longitude in decimal degrees. Overrides the line fields when set.", "anyOf": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "null" } ] } }, "additionalProperties": false }, "recipient": { "description": "The recipient of the delivery.", "type": "object", "properties": { "name": { "description": "Full name of the recipient.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "email": { "description": "Email address of the recipient.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "phone": { "description": "Phone number of the recipient.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "externalId": { "description": "The retailer's own id for this recipient in their system.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "additionalProperties": false }, "packageInfo": { "description": "Package details: products, quantities, and the retailer's own id.", "type": "object", "properties": { "products": { "description": "The products that are part of the order.", "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "packageCount": { "description": "The amount of packages in the order. A barcode is created per package. Defaults to 1.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10000 }, { "type": "null" } ] }, "packageLoadAmount": { "description": "The amount of the vehicle's load capacity this order takes up. Same unit as the retailer weight setting.", "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "externalId": { "description": "The retailer's own id for this order in their own system.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "additionalProperties": false }, "deliveryInstructions": { "description": "How and when to deliver.", "type": "object", "properties": { "notes": { "description": "Notes for the delivery. `null` clears them.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "expectedDeliveryDate": { "description": "Calendar date the retailer expects delivery on. Date-only, in the retailer's local timezone. `null` clears it.", "anyOf": [ { "description": "A date.", "type": "object", "properties": { "day": { "description": "The day of the date.", "type": "integer", "minimum": 1, "maximum": 31 }, "month": { "description": "The month of the date.", "type": "integer", "minimum": 1, "maximum": 12 }, "year": { "description": "The year of the date.", "type": "integer", "minimum": 2000, "maximum": 2100 } }, "required": ["day", "month", "year"], "additionalProperties": false }, { "type": "null" } ] }, "proofOfAttemptRequirements": { "description": "The requirements on the proof of attempt for this order.", "type": "object", "properties": { "enabled": { "description": "Whether the driver must collect proof (signature or photo) on attempt. Omitted leaves it unchanged, `null` reverts to the courier's default.", "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, "handOffInfo": { "description": "How the order is handed off to the courier.", "type": "object", "properties": { "handOffType": { "description": "The hand-off type. Omit to leave it unchanged. The stored hand-off cannot be cleared, so `null` is not accepted.", "type": "string", "enum": ["ship_to_courier", "pickup_by_courier"] }, "pickupLocationId": { "description": "The retailer location the courier picks up from. Only applies when `handOffType` is `pickup_by_courier`. An omitted id keeps the stored location, and `null` clears it: a pickup order without one picks up at the retailer's main location when submitted.", "anyOf": [ { "description": "Unique identifier of a pickup location, in the format `pickupLocations/{id}`.", "type": "string", "pattern": "^pickupLocations\\/[a-zA-Z0-9_-]{1,50}$" }, { "type": "null" } ] } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } }, "description": "Input shape accepted by `PATCH /orders/{id}`. An omitted field is left unchanged, an explicit `null` clears a nullable field, an empty nested object changes nothing, and arrays replace the whole stored array." }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[a-zA-Z0-9_-]{1,50}$" }, "in": "path", "name": "id", "required": true, "description": "The order id." } ], "responses": { "200": { "description": "The updated order.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/connectOrderIdSchema" } ], "description": "The order identifier." }, "createdAt": { "type": "number", "description": "Timestamp in seconds when the order was created." }, "recipient": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full name of the recipient." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address of the recipient." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone number of the recipient." }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The retailer's own id for this recipient in their system." } }, "required": ["name", "email", "phone", "externalId"], "additionalProperties": false, "description": "Recipient of the delivery." }, "packageInfo": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "string" }, "description": "The products that are part of the order." }, "packageCount": { "type": "number", "description": "The amount of packages that are part of the order. For every package, a barcode will be created." }, "packageLoadAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The amount of the vehicle's load capacity this order takes up. Same unit as the retailer weight setting." }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The retailer's own id for this order in their own system." } }, "required": [ "products", "packageCount", "packageLoadAmount", "externalId" ], "additionalProperties": false, "description": "Package details: products, quantities, and the retailer's own id for this order." }, "address": { "type": "object", "properties": { "address": { "type": "string", "description": "Combined address string. Computed by geocoding, and empty when the order was created from coordinates only." }, "addressLineOne": { "type": "string", "description": "First line of the address." }, "addressLineTwo": { "type": "string", "description": "Second line of the address." }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Latitude coordinate in decimal degrees." }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Longitude coordinate in decimal degrees." }, "placeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Google Places identifier for this location." }, "placeTypes": { "type": "array", "items": { "type": "string" }, "description": "Place types from the Google Places API." } }, "required": [ "address", "addressLineOne", "addressLineTwo", "latitude", "longitude", "placeId", "placeTypes" ], "additionalProperties": false, "description": "Address of the delivery as returned on an `Order`." }, "deliveryInstructions": { "type": "object", "properties": { "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Notes for the delivery." }, "expectedDeliveryDate": { "anyOf": [ { "type": "object", "properties": { "day": { "type": "integer", "minimum": 1, "maximum": 31, "description": "The day of the date." }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "The month of the date." }, "year": { "type": "integer", "minimum": 2000, "maximum": 2100, "description": "The year of the date." } }, "required": ["day", "month", "year"], "additionalProperties": false }, { "type": "null" } ], "description": "Calendar date the retailer expects delivery on. Date-only, in the retailer's local timezone." }, "proofOfAttemptRequirements": { "type": "object", "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the driver must collect proof (signature or photo) on attempt. `null` uses the courier default, `false` disables it for this order, `true` enables it following the courier per-attempt-type policies." } }, "required": ["enabled"], "additionalProperties": false, "description": "Proof-of-attempt requirements for an order." }, "handOffInfo": { "type": "object", "properties": { "handOffType": { "anyOf": [ { "type": "string", "enum": [ "ship_to_courier", "pickup_by_courier" ], "description": "How an order is handed off to the courier." }, { "type": "null" } ], "description": "The hand-off type. `ship_to_courier`: the retailer ships to the courier, no pickup. `pickup_by_courier`: the courier picks up from a retailer location. When `null`, the retailer's default applies." }, "pickupLocationId": { "anyOf": [ { "$ref": "#/components/schemas/connectPickupLocationIdSchema" }, { "type": "null" } ], "description": "The retailer location the courier picks up from when `handOffType` is `pickup_by_courier`. Must be `null` when `handOffType` is `ship_to_courier`." } }, "required": ["handOffType", "pickupLocationId"], "additionalProperties": false, "description": "How an order is handed off to the courier." } }, "required": [ "notes", "expectedDeliveryDate", "proofOfAttemptRequirements", "handOffInfo" ], "additionalProperties": false, "description": "How and when an order should be delivered: notes, the expected delivery date, proof-of-attempt requirements, and hand-off details." }, "courier": { "anyOf": [ { "$ref": "#/components/schemas/connectCourierIdSchema" }, { "type": "null" } ], "description": "The courier this order has been submitted to. `null` until the order is submitted." }, "submitted": { "type": "boolean", "description": "Whether the order has been submitted to a courier." }, "submittedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Timestamp in seconds when the order was submitted to a courier." }, "progress": { "anyOf": [ { "type": "object", "properties": { "trackingLink": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tracking link the recipient can follow." }, "eta": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": ["available"] }, "value": { "type": "object", "properties": { "estimatedArrivalAt": { "type": "number", "description": "Estimated arrival, in seconds since epoch." }, "estimatedEarliestArrivalAt": { "type": "number", "description": "Earliest arrival of the window, in seconds since epoch." }, "estimatedLatestArrivalAt": { "type": "number", "description": "Latest arrival of the window, in seconds since epoch." } }, "required": [ "estimatedArrivalAt", "estimatedEarliestArrivalAt", "estimatedLatestArrivalAt" ], "additionalProperties": false, "description": "Estimated time of arrival, with an earliest and latest window." } }, "required": ["status", "value"], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": ["restricted"] }, "restrictionCode": { "type": "string" } }, "required": ["status"], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": ["pending"] }, "pendingReason": { "type": "string" } }, "required": ["status"], "additionalProperties": false } ] }, "attempted": { "type": "boolean", "description": "Whether a delivery attempt has been completed, successful or not." }, "attemptedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Timestamp in seconds of when the driver attempted delivery." }, "state": { "type": "string", "enum": [ "delivered_to_recipient", "delivered_to_third_party", "delivered_to_mailbox", "delivered_to_safe_place", "delivered_to_pickup_point", "delivered_other", "picked_up_from_customer", "picked_up_unmanned", "picked_up_from_locker", "picked_up_other", "failed_not_home", "failed_cant_find_address", "failed_no_parking", "failed_no_time", "failed_package_not_available", "failed_missing_required_proof", "failed_payment_not_received", "failed_other", "unattempted" ], "description": "The current state of the delivery." }, "routeStartDate": { "type": "object", "properties": { "day": { "type": "integer", "minimum": 1, "maximum": 31, "description": "The day of the date." }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "The month of the date." }, "year": { "type": "integer", "minimum": 2000, "maximum": 2100, "description": "The year of the date." } }, "required": ["day", "month", "year"], "additionalProperties": false, "description": "Date the route started or is planned to start." }, "routeStarted": { "type": "boolean", "description": "Whether the route this order is on has been started by the driver." }, "succeeded": { "type": "boolean", "description": "Whether the delivery was successful." }, "photoUrls": { "type": "array", "items": { "type": "string" }, "description": "URLs of proof-of-attempt photos taken by the driver. A URL can return not-found while the driver's app is still uploading the photo." }, "signatureUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL of the captured signature image, when one was collected. Subject to the same upload delay as `photoUrls`." }, "signeeName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the signee, when a signature was collected." }, "driverProvidedRecipientNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Notes provided by the driver for the recipient." } }, "required": [ "trackingLink", "eta", "attempted", "attemptedAt", "state", "routeStartDate", "routeStarted", "succeeded", "photoUrls", "signatureUrl", "signeeName", "driverProvidedRecipientNotes" ], "additionalProperties": false, "description": "Progress for an order: ETA, attempt outcome, and any proof captured on the delivery attempt." }, { "type": "null" } ], "description": "Progress for the order. `null` until the courier assigns the order to a route." }, "readOnly": { "type": "boolean", "description": "Whether the order is read-only. Read-only orders cannot be edited or withdrawn." }, "source": { "type": "string", "enum": ["retailer", "courier"], "description": "Where the order originated. `retailer`: created by the retailer. `courier`: added by the courier on the retailer's behalf, surfaced read-only." }, "barcodes": { "type": "array", "items": { "type": "string" }, "description": "List of barcodes associated with the Order." } }, "required": [ "id", "createdAt", "recipient", "packageInfo", "address", "deliveryInstructions", "courier", "submitted", "submittedAt", "progress", "readOnly", "source", "barcodes" ], "additionalProperties": false, "description": "The updated order.", "definitions": { "connectOrderIdSchema": { "type": "string", "pattern": "^orders\\/[a-zA-Z0-9_-]{1,50}$" }, "connectPickupLocationIdSchema": { "type": "string", "pattern": "^pickupLocations\\/[a-zA-Z0-9_-]{1,50}$", "description": "Unique identifier of a pickup location, in the format `pickupLocations/{id}`." }, "connectCourierIdSchema": { "type": "string", "pattern": "^couriers\\/[a-zA-Z0-9_-]{1,50}$", "description": "Unique identifier of a courier, in the format `couriers/{id}`." } } } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "The request is invalid." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "Unauthorized" } } } }, "404": { "description": "The order does not exist, or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "enum": ["order_not_found"] } }, "required": ["message", "code"], "description": "The order does not exist, or has been deleted.", "title": "Order not found" } } } }, "409": { "description": "The order cannot be edited in its current state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "anyOf": [ { "type": "string", "enum": [ "order_read_only", "order_concurrent_modification" ] }, { "type": "string" } ] } }, "required": ["message", "code"], "description": "The order cannot be edited in its current state.", "title": "Order edit conflict" } } } }, "422": { "description": "The update could not be processed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "enum": [ "order_address_unresolvable", "order_invalid_fields" ] }, "param": { "type": "string", "description": "The parameter that caused the error." } }, "required": ["message", "code"], "description": "The update could not be processed." } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "An internal server error occurred" } } } }, "default": { "description": "The default error model", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "The default error model" } } } } } }, "delete": { "operationId": "deleteOrder", "summary": "Delete an order", "tags": ["Orders"], "description": "Delete an order for the authenticated retailer. Only a draft order can be deleted: a submitted order must be withdrawn first, and a read-only order (added by the courier, or already on a route) cannot be deleted.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[a-zA-Z0-9_-]{1,50}$" }, "in": "path", "name": "id", "required": true, "description": "The order id." } ], "responses": { "204": { "description": "The order was deleted." }, "400": { "description": "ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "ID format is invalid", "title": "The request is invalid" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "Unauthorized" } } } }, "404": { "description": "The order does not exist, or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "enum": ["order_not_found"] } }, "required": ["message", "code"], "description": "The order does not exist, or has been deleted.", "title": "Order not found" } } } }, "409": { "description": "The order cannot be deleted in its current state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "anyOf": [ { "type": "string", "enum": ["order_read_only", "order_already_submitted"] }, { "type": "string" } ] } }, "required": ["message", "code"], "description": "The order cannot be deleted in its current state.", "title": "Order delete conflict" } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "An internal server error occurred" } } } }, "default": { "description": "The default error model", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "The default error model" } } } } } } }, "/orders/{id}/shippingLabels": { "get": { "operationId": "getOrderShippingLabels", "summary": "Retrieve an order's shipping labels", "tags": ["Orders"], "description": "Render the order's shipping labels as a single PDF (A6, one Code 128 barcode per page, one page per package) and return a signed URL to it, valid for one hour. Every call renders the labels afresh and signs a new URL, so fetch it promptly server-side: the link is too short-lived to embed anywhere a recipient might open later.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[a-zA-Z0-9_-]{1,50}$" }, "in": "path", "name": "id", "required": true, "description": "The order id." } ], "responses": { "200": { "description": "A fresh signed link to the shipping-labels PDF.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Signed URL to the shipping-labels PDF. Fetchable without the API key until it expires." }, "expiresAt": { "type": "number", "description": "When the signed URL stops working, in seconds since epoch." } }, "required": ["url", "expiresAt"], "additionalProperties": false, "description": "A fresh signed link to the shipping-labels PDF." } } } }, "400": { "description": "ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "ID format is invalid", "title": "The request is invalid" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "Unauthorized" } } } }, "404": { "description": "The order does not exist, or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "enum": ["order_not_found"] } }, "required": ["message", "code"], "description": "The order does not exist, or has been deleted.", "title": "Order not found" } } } }, "422": { "description": "The shipping labels could not be generated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code, always `order_invalid_fields`.", "enum": ["order_invalid_fields"] }, "param": { "type": "string", "description": "The order field that caused the rejection." } }, "required": ["message", "code", "param"], "description": "The shipping labels could not be generated." } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "An internal server error occurred" } } } }, "default": { "description": "The default error model", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "The default error model" } } } } } } }, "/couriers": { "get": { "operationId": "listCouriers", "summary": "List couriers", "tags": ["Couriers"], "description": "List the couriers connected to the authenticated retailer.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "in": "query", "name": "pageToken", "required": false, "description": "The page token to continue from." }, { "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "maxPageSize", "required": false, "description": "The maximum number of couriers to return." } ], "responses": { "200": { "description": "The couriers connected to the retailer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "couriers": { "type": "array", "items": { "$ref": "#/components/schemas/connectCourierSchema" }, "description": "The couriers connected to the retailer." }, "nextPageToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The token for the next page, or null when there are no more couriers." } }, "required": ["couriers", "nextPageToken"], "definitions": { "connectCourierSchema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/connectCourierIdSchema" } ], "description": "Courier identifier." }, "name": { "type": "string", "description": "The courier's display name." } }, "required": ["id", "name"], "additionalProperties": false, "description": "A courier connected to the retailer." }, "connectCourierIdSchema": { "type": "string", "pattern": "^couriers\\/[a-zA-Z0-9_-]{1,50}$" } }, "description": "The couriers connected to the retailer." } } } }, "400": { "description": "Query parameters are invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "Query parameters are invalid" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "Unauthorized" } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "An internal server error occurred" } } } }, "default": { "description": "The default error model", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "The default error model" } } } } } } }, "/couriers/{id}": { "get": { "operationId": "getCourier", "summary": "Retrieve a courier", "tags": ["Couriers"], "description": "Retrieve a single courier connected to the authenticated retailer.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,50}$" }, "in": "path", "name": "id", "required": true, "description": "The courier id." } ], "responses": { "200": { "description": "The requested courier.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/connectCourierIdSchema" } ], "description": "Courier identifier." }, "name": { "type": "string", "description": "The courier's display name." } }, "required": ["id", "name"], "additionalProperties": false, "description": "The requested courier.", "definitions": { "connectCourierIdSchema": { "type": "string", "pattern": "^couriers\\/[a-zA-Z0-9_-]{1,50}$" } } } } } }, "400": { "description": "ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "ID format is invalid", "title": "The request is invalid" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "Unauthorized" } } } }, "404": { "description": "The courier is not connected to the retailer, or does not exist.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "enum": ["courier_not_found"] } }, "required": ["message", "code"], "description": "The courier is not connected to the retailer, or does not exist.", "title": "Courier not found" } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "An internal server error occurred" } } } }, "default": { "description": "The default error model", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "The default error model" } } } } } } }, "/pickupLocations": { "get": { "operationId": "listPickupLocations", "summary": "List pickup locations", "tags": ["Pickup Locations"], "description": "List the authenticated retailer's pickup locations.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "in": "query", "name": "pageToken", "required": false, "description": "The page token to continue from." }, { "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "maxPageSize", "required": false, "description": "The maximum number of pickup locations to return." } ], "responses": { "200": { "description": "The retailer's pickup locations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pickupLocations": { "type": "array", "items": { "$ref": "#/components/schemas/connectPickupLocationSchema" }, "description": "The retailer's pickup locations." }, "nextPageToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The token for the next page, or null when there are no more pickup locations." } }, "required": ["pickupLocations", "nextPageToken"], "definitions": { "connectPickupLocationSchema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/connectPickupLocationIdSchema" } ], "description": "Pickup location identifier." }, "name": { "type": "string", "description": "The location's display name." } }, "required": ["id", "name"], "additionalProperties": false, "description": "A retailer pickup location." }, "connectPickupLocationIdSchema": { "type": "string", "pattern": "^pickupLocations\\/[a-zA-Z0-9_-]{1,50}$" } }, "description": "The retailer's pickup locations." } } } }, "400": { "description": "Query parameters are invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "Query parameters are invalid" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "Unauthorized" } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "An internal server error occurred" } } } }, "default": { "description": "The default error model", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "The default error model" } } } } } } }, "/pickupLocations/{id}": { "get": { "operationId": "getPickupLocation", "summary": "Retrieve a pickup location", "tags": ["Pickup Locations"], "description": "Retrieve a single one of the authenticated retailer's pickup locations.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,50}$" }, "in": "path", "name": "id", "required": true, "description": "The pickup location id." } ], "responses": { "200": { "description": "The requested pickup location.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/connectPickupLocationIdSchema" } ], "description": "Pickup location identifier." }, "name": { "type": "string", "description": "The location's display name." } }, "required": ["id", "name"], "additionalProperties": false, "description": "The requested pickup location.", "definitions": { "connectPickupLocationIdSchema": { "type": "string", "pattern": "^pickupLocations\\/[a-zA-Z0-9_-]{1,50}$" } } } } } }, "400": { "description": "ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "ID format is invalid", "title": "The request is invalid" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "Unauthorized" } } } }, "404": { "description": "The pickup location does not belong to the retailer, or does not exist.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "enum": ["pickup_location_not_found"] } }, "required": ["message", "code"], "description": "The pickup location does not belong to the retailer, or does not exist.", "title": "Pickup location not found" } } } }, "500": { "description": "An internal server error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "An internal server error occurred" } } } }, "default": { "description": "The default error model", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." }, "code": { "type": "string", "description": "The error code." }, "param": { "type": "string", "description": "The parameter that caused the error." }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": ["message"], "description": "The default error model" } } } } } } } }, "servers": [ { "url": "https://api.spoke.com/connect/v1" } ], "security": [ { "BearerAuth": [] }, { "BasicAuth": [] } ], "tags": [ { "name": "Orders", "description": "Create, submit, and track delivery orders, and download their printable PDF labels.\n" }, { "name": "Couriers", "description": "Look up the couriers that deliver your orders.\n" }, { "name": "Pickup Locations", "description": "Look up the pickup locations your orders ship from.\n" } ] }