> ## 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. # Get request status > Returns the current status and outcome of a label-purchase request. Read-only and safe to call repeatedly. Poll while `status` is `processing`. Terminal outcomes are `purchased`, `dry_run_completed`, `no_match`, and `failed`. The `dry_run` field identifies dry runs, which can also end in `no_match` or `failed`. A `no_match` outcome includes `reason.code` and `reason.message`: rules and fallback selected nothing (`no_match`), every returned rate was excluded from automatic selection (`all_rates_excluded`), or no rates were returned for the shipment (`no_rates_returned`). Reason codes may be added; tolerate unknown codes. `purchased` and `dry_run_completed` need no reason. A successful poll returns HTTP 200 for every outcome. Only `failed` includes `error`; branch on its code and tolerate additional codes. A failed automation may have an unconfirmed purchase: check the account or transaction before retrying when instructed by the error. Returns `404` for a request id that does not exist or does not belong to your account. ## OpenAPI ````yaml /api-reference/automationsapi/openapi.yaml get /automations/labels/{request_id} 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/{request_id}: get: tags: - Automations summary: Get request status description: >- Returns the current status and outcome of a label-purchase request. Read-only and safe to call repeatedly. Poll while `status` is `processing`. Terminal outcomes are `purchased`, `dry_run_completed`, `no_match`, and `failed`. The `dry_run` field identifies dry runs, which can also end in `no_match` or `failed`. A `no_match` outcome includes `reason.code` and `reason.message`: rules and fallback selected nothing (`no_match`), every returned rate was excluded from automatic selection (`all_rates_excluded`), or no rates were returned for the shipment (`no_rates_returned`). Reason codes may be added; tolerate unknown codes. `purchased` and `dry_run_completed` need no reason. A successful poll returns HTTP 200 for every outcome. Only `failed` includes `error`; branch on its code and tolerate additional codes. A failed automation may have an unconfirmed purchase: check the account or transaction before retrying when instructed by the error. Returns `404` for a request id that does not exist or does not belong to your account. operationId: getAutomationsLabel parameters: - name: request_id in: path required: true schema: type: string format: uuid title: Request Id responses: '200': description: Successful Response content: application/json: schema: oneOf: - $ref: '#/components/schemas/ProcessingStatus' - $ref: '#/components/schemas/DryRunCompletedStatus' - $ref: '#/components/schemas/PurchasedStatus' - $ref: '#/components/schemas/NoMatchStatus' - $ref: '#/components/schemas/FailedStatus' discriminator: propertyName: status mapping: processing: '#/components/schemas/ProcessingStatus' dry_run_completed: '#/components/schemas/DryRunCompletedStatus' purchased: '#/components/schemas/PurchasedStatus' no_match: '#/components/schemas/NoMatchStatus' failed: '#/components/schemas/FailedStatus' title: Response 200 Getautomationslabel '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' '404': description: No automation request with that id. content: application/json: 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: ProcessingStatus: properties: request_id: type: string format: uuid title: Request Id test: type: boolean title: Test description: Whether this request was created in test mode. status: type: string const: processing title: Status description: Automation processing is still in progress. dry_run: type: boolean title: Dry Run description: Whether this request evaluates selection without purchasing a label. created_at: type: string format: date-time title: Created At message: type: string title: Message type: object required: - request_id - test - status - dry_run - created_at - message title: ProcessingStatus examples: - request_id: b3b8f6b0-1a2b-4c3d-9e4f-5a6b7c8d9e0f test: false status: processing dry_run: false created_at: '2026-09-03T18:04:10Z' message: Fetching rates. DryRunCompletedStatus: properties: request_id: type: string format: uuid title: Request Id test: type: boolean title: Test description: Whether this request was created in test mode. status: type: string const: dry_run_completed title: Status description: A rate was selected; no purchase was attempted. dry_run: type: boolean title: Dry Run description: True for a completed dry run; no label is purchased. shipment_id: anyOf: - type: string - type: 'null' title: Shipment Id decision_log_id: anyOf: - type: string format: uuid - type: 'null' title: Decision Log Id selected_rate: anyOf: - $ref: '#/components/schemas/SelectedRate' - type: 'null' matched_rule_name: anyOf: - type: string - type: 'null' title: Matched Rule Name matched_priority: anyOf: - type: integer - type: 'null' title: Matched Priority fallback_triggered: anyOf: - type: boolean - type: 'null' title: Fallback Triggered evaluated_at: anyOf: - type: string format: date-time - type: 'null' title: Evaluated At created_at: type: string format: date-time title: Created At type: object required: - request_id - test - status - dry_run - created_at title: DryRunCompletedStatus examples: - request_id: b3b8f6b0-1a2b-4c3d-9e4f-5a6b7c8d9e0f test: false status: dry_run_completed dry_run: true decision_log_id: c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f selected_rate: rate_id: c4e8a2f6d0b94c17a3e5f7b9d1c3e5a7 carrier: USPS service_level: usps_priority amount: '7.35' matched_rule_name: default matched_priority: 1 fallback_triggered: false evaluated_at: '2026-09-03T18:04:12Z' created_at: '2026-09-03T18:04:10Z' PurchasedStatus: properties: request_id: type: string format: uuid title: Request Id test: type: boolean title: Test description: Whether this request was created in test mode. status: type: string const: purchased title: Status description: The label was purchased. dry_run: type: boolean title: Dry Run description: >- Whether the request was submitted as a dry run. Normally false for purchased requests; use status to determine the purchase outcome. shipment_id: anyOf: - type: string - type: 'null' title: Shipment Id transaction_id: anyOf: - type: string - type: 'null' title: Transaction Id tracking_number: anyOf: - type: string - type: 'null' title: Tracking Number label_url: anyOf: - type: string - type: 'null' title: Label Url selected_rate: anyOf: - $ref: '#/components/schemas/SelectedRate' - type: 'null' matched_rule_name: anyOf: - type: string - type: 'null' title: Matched Rule Name matched_priority: anyOf: - type: integer - type: 'null' title: Matched Priority fallback_triggered: anyOf: - type: boolean - type: 'null' title: Fallback Triggered decision_log_id: anyOf: - type: string format: uuid - type: 'null' title: Decision Log Id evaluated_at: anyOf: - type: string format: date-time - type: 'null' title: Evaluated At label_processed_at: anyOf: - type: string format: date-time - type: 'null' title: Label Processed At created_at: type: string format: date-time title: Created At type: object required: - request_id - test - status - dry_run - created_at title: PurchasedStatus examples: - request_id: b3b8f6b0-1a2b-4c3d-9e4f-5a6b7c8d9e0f test: false status: purchased dry_run: false shipment_id: 5e40ead7cffe4cc1ad45108696162e42 transaction_id: 9b2d4f6a8c0e4a1b3d5f7a9c1e3b5d7f tracking_number: '9400111899223197428490' label_url: >- https://shippo-delivery.s3.amazonaws.com/2f8b6d1e4a9c4f3b8e7d5a1c6b9e0f24.pdf selected_rate: rate_id: c4e8a2f6d0b94c17a3e5f7b9d1c3e5a7 carrier: USPS service_level: usps_priority amount: '7.35' matched_rule_name: default matched_priority: 1 fallback_triggered: false decision_log_id: c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f evaluated_at: '2026-09-03T18:04:12Z' label_processed_at: '2026-09-03T18:04:20Z' created_at: '2026-09-03T18:04:10Z' NoMatchStatus: properties: request_id: type: string format: uuid title: Request Id test: type: boolean title: Test description: Whether this request was created in test mode. status: type: string const: no_match title: Status description: >- No eligible rate was selected; no purchase was attempted. See reason for the explanation. reason: $ref: '#/components/schemas/ReasonBody' description: >- Why no rate was selected. This is a non-error outcome; branch on code, not message. dry_run: type: boolean title: Dry Run description: Whether this request evaluates selection without purchasing a label. shipment_id: anyOf: - type: string - type: 'null' title: Shipment Id decision_log_id: anyOf: - type: string format: uuid - type: 'null' title: Decision Log Id evaluated_at: anyOf: - type: string format: date-time - type: 'null' title: Evaluated At created_at: type: string format: date-time title: Created At type: object required: - request_id - test - status - reason - dry_run - created_at title: NoMatchStatus examples: - request_id: b3b8f6b0-1a2b-4c3d-9e4f-5a6b7c8d9e0f test: false status: no_match dry_run: false reason: code: no_match message: No rate was selected by your rules or fallback. created_at: '2026-09-03T18:04:10Z' - request_id: b3b8f6b0-1a2b-4c3d-9e4f-5a6b7c8d9e0f test: false status: no_match dry_run: true reason: code: all_rates_excluded message: No returned rates were eligible for automatic selection. created_at: '2026-09-03T18:04:10Z' - request_id: b3b8f6b0-1a2b-4c3d-9e4f-5a6b7c8d9e0f test: false status: no_match dry_run: false reason: code: no_rates_returned message: >- We couldn't find rates for this shipment. Review your details and try again. created_at: '2026-09-03T18:04:10Z' FailedStatus: properties: request_id: type: string format: uuid title: Request Id test: type: boolean title: Test description: Whether this request was created in test mode. status: type: string const: failed title: Status description: >- Automation processing ended unsuccessfully. The error code describes the purchase outcome and next steps. dry_run: type: boolean title: Dry Run description: Whether this request evaluates selection without purchasing a label. shipment_id: anyOf: - type: string - type: 'null' title: Shipment Id decision_log_id: anyOf: - type: string format: uuid - type: 'null' title: Decision Log Id selected_rate: anyOf: - $ref: '#/components/schemas/SelectedRate' - type: 'null' transaction_id: anyOf: - type: string - type: 'null' title: Transaction Id error: $ref: '#/components/schemas/ErrorBody' evaluated_at: anyOf: - type: string format: date-time - type: 'null' title: Evaluated At created_at: type: string format: date-time title: Created At type: object required: - request_id - test - status - dry_run - error - created_at title: FailedStatus examples: - request_id: b3b8f6b0-1a2b-4c3d-9e4f-5a6b7c8d9e0f test: false status: failed dry_run: false error: code: address_validation_failed message: An address could not be validated. Check the address details. created_at: '2026-09-03T18:04:10Z' - request_id: b3b8f6b0-1a2b-4c3d-9e4f-5a6b7c8d9e0f test: false status: failed dry_run: false shipment_id: 5e40ead7cffe4cc1ad45108696162e42 transaction_id: 9b2d4f6a8c0e4a1b3d5f7a9c1e3b5d7f error: code: pipeline_dropped_purchase_unresolved message: >- The label purchase was submitted but its outcome could not be confirmed. Please check the transaction before retrying to avoid a duplicate label. created_at: '2026-09-03T18:04:10Z' 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 SelectedRate: properties: rate_id: type: string title: Rate Id description: Shippo rate object id that was selected. carrier: type: string title: Carrier description: Carrier of the selected rate (e.g. "USPS"). service_level: type: string title: Service Level description: Service-level token of the selected rate (e.g. "usps_priority"). amount: type: string title: Amount description: >- Rate amount as a decimal string, matching the Shippo rate contract (e.g. "7.50"). type: object required: - rate_id - carrier - service_level - amount title: SelectedRate ReasonBody: properties: code: type: string title: Code description: >- Stable non-error reason code. Integrations must tolerate additional codes. message: type: string minLength: 1 title: Message description: Customer-safe explanation. Wording may change. type: object required: - code - message title: ReasonBody ErrorBody: properties: code: type: string title: Code description: Stable error code. Integrations must tolerate additional codes. message: type: string minLength: 1 title: Message description: Customer-safe explanation. Wording may change. type: object required: - code - message title: ErrorBody 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 - [Get Carrier Registration status](/api-reference/carrier-accounts/get-carrier-registration-status.md) - [Get a tracking status](/api-reference/tracking-status/get-a-tracking-status.md) - [List label-purchase requests](/api-reference/automations/list-label-purchase-requests.md)