> ## Documentation Index > Fetch the complete documentation index at: https://docs.goshippo.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Shippo is a multi-carrier shipping API. For agent integrations that execute shipping operations (rates, labels, tracking, address validation, customs), connect the hosted Shippo MCP server at https://mcp.shippo.com (per-user OAuth; setup at /guides/mcp-server). To search and read this documentation from an agent, a docs search MCP is available at https://docs.goshippo.com/mcp. Shipping workflow knowledge (agent skills and a knowledge pack) is published at https://github.com/goshippo/ai. For REST integrations start at /guides/api-quickstart; test mode uses shippo_test_ API keys. # Buy a label using your automation rules > Purchases a shipping label. **This spends money.** A successful request charges your Shippo account for the selected rate; it cannot be undone through this API (refunds go through the [Refunds API](https://docs.goshippo.com/api-reference/refunds/create-a-refund)). Send `dry_run: true` to see which rate the rules would select, with no purchase and no charge. Automated callers should dry-run an unfamiliar shipment shape before running it live. The request body is the standard Shippo `POST /shipments` create body, plus `dry_run`; any field that endpoint accepts is passed through unchanged. Responds `202` with a `request_id` and a `poll_url`. Work continues asynchronously — poll `GET /automations/labels/{request_id}` until `status` reaches a terminal state (`purchased`, `dry_run_completed`, `no_match`, or `failed`). The `Idempotency-Key` header is required. Repeating a **live** request with the same key returns a pointer to the original request instead of creating a duplicate; dry runs are never deduplicated (each `dry_run` request starts a new evaluation). ## OpenAPI ````yaml /api-reference/automationsapi/openapi.yaml post /automations/labels openapi: 3.1.0 info: title: Automations API description: >- Buy the right label in one call. Shipping a parcel through the Shippo API takes four steps today: create a shipment, fetch rates, compare them against your own logic, then buy the label. Automations collapses that into one request. You send the shipment, Shippo applies your rules, selects the rate, and buys the label. ## What the rules are In this beta, every account is provisioned with exactly one rule, named `default`, which selects the lowest-cost eligible rate for the shipment. A few USPS service levels whose eligibility Automations can't check, such as Media Mail, are never selected; see [Service levels the rule never selects](https://docs.goshippo.com/automations/automations#service-levels-the-rule-never-selects). The rule is created for you the first time you call the API. There is nothing to configure, and there is no endpoint for authoring or editing rules yet. Customer-defined rules are planned for a later release. ## Decision transparency Every request keeps a decision record. `GET /automations/labels/{request_id}/decision` returns the rule that matched, the rate selected, the facts the engine evaluated, and the full rule trace. Use it to answer "why this carrier, why this price" without building and instrumenting your own rate-comparison logic. ## Beta status These endpoints are in beta. Request and response shapes may change without the notice period that applies to generally available Shippo endpoints, and they are not yet covered by the `SHIPPO-API-VERSION` header. Breaking changes are announced to enrolled accounts before they ship. Pin nothing in production that you cannot redeploy. contact: name: Shippo API Support url: https://support.goshippo.com/ version: beta servers: - url: https://api.goshippo.com description: Shippo API security: - ShippoToken: [] tags: - name: Automations description: >- Rules-based, single-call label purchase. Create a request, list requests, poll a request's status, and read the decision behind a selected rate. externalDocs: description: Shippo API reference, including the full shipment field list url: https://docs.goshippo.com/api-reference/shipments/create-a-new-shipment paths: /automations/labels: post: tags: - Automations summary: Buy a label using your automation rules description: >- Purchases a shipping label. **This spends money.** A successful request charges your Shippo account for the selected rate; it cannot be undone through this API (refunds go through the [Refunds API](https://docs.goshippo.com/api-reference/refunds/create-a-refund)). Send `dry_run: true` to see which rate the rules would select, with no purchase and no charge. Automated callers should dry-run an unfamiliar shipment shape before running it live. The request body is the standard Shippo `POST /shipments` create body, plus `dry_run`; any field that endpoint accepts is passed through unchanged. Responds `202` with a `request_id` and a `poll_url`. Work continues asynchronously — poll `GET /automations/labels/{request_id}` until `status` reaches a terminal state (`purchased`, `dry_run_completed`, `no_match`, or `failed`). The `Idempotency-Key` header is required. Repeating a **live** request with the same key returns a pointer to the original request instead of creating a duplicate; dry runs are never deduplicated (each `dry_run` request starts a new evaluation). operationId: createAutomationsLabel parameters: - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 255 title: Idempotency-Key description: >- Required. A client-generated key that makes retries safe: repeating a request with the same key returns the original result instead of creating a duplicate. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AutomationsLabelRequest' examples: inline: summary: Inline addresses + parcel value: address_from: name: Acme street1: 215 Clayton St city: San Francisco state: CA zip: '94117' country: US address_to: name: Casey street1: 965 Mission St city: San Francisco state: CA zip: '94103' country: US parcels: - length: '10' width: '8' height: '4' distance_unit: in weight: '2' mass_unit: lb dry_run: summary: Dry run (evaluate, do not purchase) value: address_from: d799c2679e644279b59fe661ac8fa489 address_to: 3f8a1c2b4d5e6f708192a3b4c5d6e7f8 parcels: - a1b2c3d4e5f60718293a4b5c6d7e8f90 dry_run: true responses: '202': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AcceptedResponse' '401': description: >- Missing or invalid API token. The `detail` message depends on the problem; the example is the response when no token is sent. content: application/json: example: detail: Authentication credentials were not provided. schema: $ref: '#/components/schemas/DetailResponse' '403': description: This account does not have access to Automations. content: application/json: example: detail: Automations is not available for this account. schema: $ref: '#/components/schemas/DetailResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '503': description: Automations is temporarily unavailable. Retry later. content: application/json: example: detail: Automations is temporarily unavailable. schema: $ref: '#/components/schemas/DetailResponse' components: schemas: AutomationsLabelRequest: properties: address_from: anyOf: - $ref: '#/components/schemas/AddressCreate' - type: string description: >- An existing Shippo address object_id (typically a 32-character hex string, e.g. "d799c2679e644279b59fe661ac8fa489"). https://docs.goshippo.com/api-reference/shipments/create-a-new-shipment title: Address From description: >- Origin: an inline address object or an existing address id. https://docs.goshippo.com/api-reference/shipments/create-a-new-shipment#body-address-from-one-of-0 address_to: anyOf: - $ref: '#/components/schemas/AddressCreate' - type: string description: >- An existing Shippo address object_id (typically a 32-character hex string, e.g. "d799c2679e644279b59fe661ac8fa489"). https://docs.goshippo.com/api-reference/shipments/create-a-new-shipment title: Address To description: >- Destination: an inline address object or an existing address id. https://docs.goshippo.com/api-reference/shipments/create-a-new-shipment#body-address-to-one-of-0 parcels: anyOf: - $ref: '#/components/schemas/ParcelCreate' - items: anyOf: - $ref: '#/components/schemas/ParcelCreate' - type: string description: >- An existing Shippo parcel object_id (typically a 32-character hex string, e.g. "a1b2c3d4e5f60718293a4b5c6d7e8f90"). https://docs.goshippo.com/api-reference/shipments/create-a-new-shipment#body-parcels type: array title: Parcels description: >- One parcel object, a list of parcel objects, or a list of parcel ids. https://docs.goshippo.com/api-reference/shipments/create-a-new-shipment#body-parcels dry_run: type: boolean title: Dry Run description: >- When true, evaluate rules and select a rate but do NOT purchase a label. Requires a genuine JSON boolean (no coercion). default: false additionalProperties: true type: object required: - address_from - address_to - parcels title: AutomationsLabelRequest description: >- The body for `POST /automations/labels`: the Shippo create-shipment body plus `dry_run`. Any field that endpoint accepts is passed through unchanged, so the shipment Shippo rates and buys is exactly the one you sent. Only the address and parcel fields are described here; for the full field list, see [Create a new shipment](https://docs.goshippo.com/api-reference/shipments/create-a-new-shipment). AcceptedResponse: properties: request_id: type: string format: uuid title: Request Id status: $ref: '#/components/schemas/AutomationsLabelStatus' description: Current status of the request. poll_url: type: string title: Poll Url type: object required: - request_id - status - poll_url title: AcceptedResponse description: >- Returned by `POST /automations/labels`: a pointer to the accepted request. Repeating a live request with the same `Idempotency-Key` returns the original request's pointer, with `status` showing that request's current outcome. example: poll_url: /automations/labels/b3b8f6b0-1a2b-4c3d-9e4f-5a6b7c8d9e0f request_id: b3b8f6b0-1a2b-4c3d-9e4f-5a6b7c8d9e0f status: processing DetailResponse: properties: detail: type: string title: Detail description: Human-readable explanation of why the request could not be served. type: object required: - detail title: DetailResponse description: An error with a single human-readable `detail` message. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError AddressCreate: properties: name: type: string minLength: 1 title: Name description: Recipient/sender full name. street1: type: string minLength: 1 title: Street1 description: Primary street line. city: type: string minLength: 1 title: City description: City / locality. state: anyOf: - type: string minLength: 1 - type: 'null' title: State description: State / province. Required for some countries (e.g. US, CA). zip: anyOf: - type: string minLength: 1 - type: 'null' title: Zip description: Postal / ZIP code. Required for some countries. country: type: string minLength: 1 title: Country description: ISO 3166-1 alpha-2 country code (e.g. "US"). additionalProperties: true type: object required: - name - street1 - city - country title: AddressCreate description: >- An inline Shippo address. The fields every shippable address needs are required; `state` and `zip` are optional because only some countries require them. To reuse an address you already created, pass its `object_id` string instead. Any other valid Shippo address field (for example `company`, `phone`, `email`, `validate`) is accepted and passed through unchanged. ParcelCreate: properties: template: anyOf: - type: string minLength: 1 - type: 'null' title: Template description: >- Carrier package template token (e.g. "USPS_FlatRateEnvelope"). When set, the template supplies the dimensions and length/width/height/distance_unit may be omitted. length: anyOf: - type: string minLength: 1 - type: 'null' title: Length description: >- Length (unit set by distance_unit). Required unless `template` is set. width: anyOf: - type: string minLength: 1 - type: 'null' title: Width description: >- Width (unit set by distance_unit). Required unless `template` is set. height: anyOf: - type: string minLength: 1 - type: 'null' title: Height description: >- Height (unit set by distance_unit). Required unless `template` is set. distance_unit: anyOf: - type: string minLength: 1 - type: 'null' title: Distance Unit description: >- Unit for length/width/height (e.g. "in", "cm"). Required unless `template` is set. weight: type: string minLength: 1 title: Weight description: Weight (unit set by mass_unit). mass_unit: type: string minLength: 1 title: Mass Unit description: Unit for weight (e.g. "lb", "kg"). additionalProperties: true type: object required: - weight - mass_unit title: ParcelCreate description: >- An inline Shippo parcel. Give its dimensions one of two ways: `length`, `width`, `height`, and `distance_unit`, or a carrier package `template` that supplies them. `weight` and `mass_unit` are always required, because a template sets the box size but not the weight of its contents. To reuse a parcel you already created, pass its `object_id` string instead. Any other valid Shippo parcel field (for example `metadata`, `extra`) is accepted and passed through unchanged. AutomationsLabelStatus: type: string enum: - processing - purchased - dry_run_completed - no_match - failed title: AutomationsLabelStatus ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: ShippoToken: type: apiKey in: header name: Authorization x-token-prefix: ShippoToken x-token-format: ShippoToken {token} x-default: 'ShippoToken ' description: 'Shippo API token, sent as `Authorization: ShippoToken `.' ```` ## Related topics - [Automations](/automations/automations.md) - [Get the decision behind a selected rate](/api-reference/automations/get-the-decision-behind-a-selected-rate.md) - [Get request status](/api-reference/automations/get-request-status.md)