> ## 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 the decision behind a selected rate > Returns the rule-evaluation decision for a request: the rule that matched, the rate selected, the facts the engine evaluated, and the full rule trace. Read-only. This is the answer to "why this carrier, why this price" — the audit record for the decision; it does not change once written. In this beta the matched rule is always `default`, the single rule provisioned for your account. `matched_priority` and `fallback_triggered` describe ordering and fallback behavior that become meaningful when customer-defined rules ship. Available once evaluation has written a decision, including while a purchase is still `processing`. Outcomes reached before evaluation have no decision and return `409`, and `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}/decision 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}/decision: get: tags: - Automations summary: Get the decision behind a selected rate description: >- Returns the rule-evaluation decision for a request: the rule that matched, the rate selected, the facts the engine evaluated, and the full rule trace. Read-only. This is the answer to "why this carrier, why this price" — the audit record for the decision; it does not change once written. In this beta the matched rule is always `default`, the single rule provisioned for your account. `matched_priority` and `fallback_triggered` describe ordering and fallback behavior that become meaningful when customer-defined rules ship. Available once evaluation has written a decision, including while a purchase is still `processing`. Outcomes reached before evaluation have no decision and return `409`, and `404` for a request id that does not exist or does not belong to your account. operationId: getAutomationsLabelDecision 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: $ref: '#/components/schemas/DecisionResponse' '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' '409': description: Evaluation has not completed; no decision to return yet. 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: DecisionResponse: 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: $ref: '#/components/schemas/AutomationsLabelStatus' description: Current status of the request. 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 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 created_at: type: string format: date-time title: Created At 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 decision: $ref: '#/components/schemas/DecisionBlock' type: object required: - request_id - test - status - dry_run - created_at - decision title: DecisionResponse description: >- Returned by `GET /automations/labels/{request_id}/decision`: the request's status and identifiers plus its full decision record. Available once rule evaluation has completed. 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 created_at: '2026-09-03T18:04:10Z' evaluated_at: '2026-09-03T18:04:12Z' label_processed_at: '2026-09-03T18:04:20Z' decision: decision_log_id: c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f auto_provisioned: true estimate_available: false matched_rule_name: default matched_priority: 1 fallback_triggered: false selected_rate: rate_id: c4e8a2f6d0b94c17a3e5f7b9d1c3e5a7 carrier: USPS service_level: usps_priority amount: '7.35' facts_input: planned_ship_date: null ruleset_snapshot: rule_set_id: d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70 fallback: strategy: min_field field: cost rules: - priority: 1 rule_id: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a81 name: default version: 1 condition_groups: [] action: strategy: min_field field: cost rule_trace: - priority: 1 rule_id: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a81 rule_name: default rule_version: 1 matched: true short_circuited: false condition_results: [] selection: strategy: min_field field: cost winner_id: c4e8a2f6d0b94c17a3e5f7b9d1c3e5a7 values_considered: - rate_id: c4e8a2f6d0b94c17a3e5f7b9d1c3e5a7 value: '7.35' - rate_id: 7a1c3e5b9d2f4a6c8e0b1d3f5a7c9e2b value: '9.85' tiebreaker_applied: false tiebreaker_resolved_by: null tied_candidates: [] 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 AutomationsLabelStatus: type: string enum: - processing - purchased - dry_run_completed - no_match - failed title: AutomationsLabelStatus DecisionBlock: properties: decision_log_id: type: string format: uuid title: Decision Log Id auto_provisioned: type: boolean title: Auto Provisioned estimate_available: type: boolean title: Estimate Available matched_rule_name: anyOf: - type: string - type: 'null' title: Matched Rule Name matched_priority: anyOf: - type: integer - type: 'null' title: Matched Priority fallback_triggered: type: boolean title: Fallback Triggered selected_rate: anyOf: - $ref: '#/components/schemas/SelectedRate' - type: 'null' facts_input: additionalProperties: true type: object title: Facts Input ruleset_snapshot: anyOf: - additionalProperties: true type: object - type: 'null' title: Ruleset Snapshot rule_trace: items: additionalProperties: true type: object type: array title: Rule Trace type: object required: - decision_log_id - auto_provisioned - estimate_available - fallback_triggered - facts_input - rule_trace title: DecisionBlock description: >- The record of one completed rule evaluation: the rule that matched, the rate selected, the facts evaluated, and the full rule trace. It is written once and never changes. `estimate_available` is always `false` in this beta. 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 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 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 request status](/api-reference/automations/get-request-status.md) - [Automations](/automations/automations.md) - [Generate your first label](/guides/generate-shipping-label.md)