{"openapi":"3.1.0","info":{"title":"321label API","description":"Buy a shipping label in a few steps — built agent-first.\n\nOne contract, three transports: this REST API, the website at\n[321label.com](https://321label.com) (plus the account area at\n[321label.com/account](https://321label.com/account)), and the MCP server at\n`https://mcp.321label.com` all drive the same core.\n\n**Sandbox everywhere**: send `\"sandbox\": true` on any request for a full\nend-to-end dry-run against carrier test environments — nothing is charged,\nnothing persisted carrier-side.\n\nCarrier is always abstracted: ask for `cheapest`, `fastest`, or a named\ncarrier. Quotes honor a concrete carrier filter; on label creation the\ncarrier choice is advisory today (routing is by service + destination).\n","version":"0.1.0"},"servers":[{"url":"https://321label.com"}],"paths":{"/v1/auth/magic-link":{"post":{"summary":"Request Magic Link","operationId":"request_magic_link_v1_auth_magic_link_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/auth/magic-link/verify":{"post":{"summary":"Verify Magic Link","operationId":"verify_magic_link_v1_auth_magic_link_verify_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/auth/session":{"get":{"summary":"Get Session","description":"Always 200. Reads session cookie directly to return the full user shape\n(name, lang) that resolve_caller's Caller does not expose.","operationId":"get_session_v1_auth_session_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/auth/reauth":{"post":{"summary":"Request Reauth","operationId":"request_reauth_v1_auth_reauth_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/auth/logout":{"post":{"summary":"Logout","operationId":"logout_v1_auth_logout_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/auth/logout-all":{"post":{"summary":"Logout All","operationId":"logout_all_v1_auth_logout_all_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/auth/sessions":{"get":{"summary":"List Sessions","operationId":"list_sessions_v1_auth_sessions_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/auth/sessions/{session_id}":{"delete":{"summary":"Revoke Session","operationId":"revoke_session_v1_auth_sessions__session_id__delete","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account":{"get":{"summary":"Get Account","operationId":"get_account_v1_account_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"patch":{"summary":"Update Account","operationId":"update_account_v1_account_patch","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/labels/batch-print":{"post":{"summary":"Batch Print Labels","operationId":"batch_print_labels_v1_labels_batch_print_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/labels/batch-print/{signed_token}":{"get":{"summary":"Batch Print Download","description":"PUBLIC path — the signed HMAC token is the sole credential.","operationId":"batch_print_download_v1_labels_batch_print__signed_token__get","parameters":[{"name":"signed_token","in":"path","required":true,"schema":{"type":"string","title":"Signed Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/manifests":{"get":{"summary":"List Manifests","operationId":"list_manifests_v1_manifests_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"summary":"Create Manifest","operationId":"create_manifest_v1_manifests_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/manifests/{manifest_id}/pdf":{"get":{"summary":"Get Manifest Pdf","operationId":"get_manifest_pdf_v1_manifests__manifest_id__pdf_get","parameters":[{"name":"manifest_id","in":"path","required":true,"schema":{"type":"string","title":"Manifest Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/labels":{"get":{"summary":"List Labels","operationId":"list_labels_v1_labels_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"summary":"Create a shipping label","description":"Mints a label via the engine. `sandbox:true` = full dry-run. Live guest flow returns `202 awaiting_payment` + `payment_url` (mode 1) or `issued_unpaid` + 60-min deadline (`payment_mode:\"issue_now\"`, mode 4). Send an `Idempotency-Key` header to make retries safe.","operationId":"create_label_v1_labels_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/exports/labels.csv":{"get":{"summary":"Export Labels Csv","operationId":"export_labels_csv_v1_exports_labels_csv_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/wallet":{"get":{"summary":"Get Wallet Route","operationId":"get_wallet_route_v1_wallet_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/wallet/topups":{"post":{"summary":"Create Topup Route","operationId":"create_topup_route_v1_wallet_topups_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/wallet/topups/{topup_id}":{"get":{"summary":"Get Topup Route","operationId":"get_topup_route_v1_wallet_topups__topup_id__get","parameters":[{"name":"topup_id","in":"path","required":true,"schema":{"type":"string","title":"Topup Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/wallet/transactions":{"get":{"summary":"Transactions Route","operationId":"transactions_route_v1_wallet_transactions_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/exports/transactions.csv":{"get":{"summary":"Export Transactions Route","operationId":"export_transactions_route_v1_exports_transactions_csv_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/wallet/alerts":{"put":{"summary":"Set Alerts Route","operationId":"set_alerts_route_v1_wallet_alerts_put","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/wallet/auto-topup":{"get":{"summary":"Get Auto Topup Route","operationId":"get_auto_topup_route_v1_wallet_auto_topup_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"put":{"summary":"Set Auto Topup Route","operationId":"set_auto_topup_route_v1_wallet_auto_topup_put","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/wallet/payment-method":{"post":{"summary":"Create Payment Method Route","description":"Start a Mollie `sequenceType=first` top-up to set up the auto top-up mandate.\n\nReturns {topup_id, checkout_url}. Session only.","operationId":"create_payment_method_route_v1_wallet_payment_method_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"delete":{"summary":"Delete Payment Method Route","description":"Remove the saved payment method and disable auto top-up.\n\nRevokes the Mollie mandate (best-effort). Session only.","operationId":"delete_payment_method_route_v1_wallet_payment_method_delete","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/invoices":{"get":{"summary":"List Invoices","operationId":"list_invoices_v1_invoices_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/invoices/{invoice_id}":{"get":{"summary":"Get Invoice","operationId":"get_invoice_v1_invoices__invoice_id__get","parameters":[{"name":"invoice_id","in":"path","required":true,"schema":{"type":"string","title":"Invoice Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/invoices/{invoice_id}/pdf":{"get":{"summary":"Get Invoice Pdf","operationId":"get_invoice_pdf_v1_invoices__invoice_id__pdf_get","parameters":[{"name":"invoice_id","in":"path","required":true,"schema":{"type":"string","title":"Invoice Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/labels/{order_id}/invoice":{"get":{"summary":"Get Order Invoice Pdf","operationId":"get_order_invoice_pdf_v1_labels__order_id__invoice_get","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/invoices/close-period":{"post":{"summary":"Close Period","operationId":"close_period_v1_invoices_close_period_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/wallet/withdrawable":{"get":{"summary":"Withdrawable Route","operationId":"withdrawable_route_v1_wallet_withdrawable_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/wallet/withdrawals":{"get":{"summary":"List Withdrawals Route","operationId":"list_withdrawals_route_v1_wallet_withdrawals_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"summary":"Create Withdrawal Route","operationId":"create_withdrawal_route_v1_wallet_withdrawals_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/account/export":{"post":{"summary":"Request Export","operationId":"request_export_v1_account_export_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/account/exports/{request_id}":{"get":{"summary":"Get Export","operationId":"get_export_v1_account_exports__request_id__get","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account/exports/{request_id}/download":{"get":{"summary":"Download Export","operationId":"download_export_v1_account_exports__request_id__download_get","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account/close":{"post":{"summary":"Close Account","operationId":"close_account_v1_account_close_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/api-keys":{"get":{"summary":"List Api Keys","operationId":"list_api_keys_v1_api_keys_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"summary":"Create Api Key","operationId":"create_api_key_v1_api_keys_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/api-keys/{credential_id}":{"patch":{"summary":"Update Api Key","operationId":"update_api_key_v1_api_keys__credential_id__patch","parameters":[{"name":"credential_id","in":"path","required":true,"schema":{"type":"string","title":"Credential Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"summary":"Revoke Api Key","operationId":"revoke_api_key_v1_api_keys__credential_id__delete","parameters":[{"name":"credential_id","in":"path","required":true,"schema":{"type":"string","title":"Credential Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/api-keys/{credential_id}/rotate":{"post":{"summary":"Rotate Api Key","operationId":"rotate_api_key_v1_api_keys__credential_id__rotate_post","parameters":[{"name":"credential_id","in":"path","required":true,"schema":{"type":"string","title":"Credential Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/agent-tokens":{"get":{"summary":"List Agent Tokens","operationId":"list_agent_tokens_v1_agent_tokens_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"summary":"Create Agent Token","operationId":"create_agent_token_v1_agent_tokens_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/agent-tokens/{credential_id}":{"patch":{"summary":"Update Agent Token","operationId":"update_agent_token_v1_agent_tokens__credential_id__patch","parameters":[{"name":"credential_id","in":"path","required":true,"schema":{"type":"string","title":"Credential Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"summary":"Revoke Agent Token","operationId":"revoke_agent_token_v1_agent_tokens__credential_id__delete","parameters":[{"name":"credential_id","in":"path","required":true,"schema":{"type":"string","title":"Credential Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/agent-tokens/{credential_id}/rotate":{"post":{"summary":"Rotate Agent Token","operationId":"rotate_agent_token_v1_agent_tokens__credential_id__rotate_post","parameters":[{"name":"credential_id","in":"path","required":true,"schema":{"type":"string","title":"Credential Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account/spend-limit":{"put":{"summary":"Set Spend Limit","description":"Set (number ≥ 0) or clear (null) the account-wide daily spend cap.\n\n`daily` is decimal major units on the wire; stored as integer minor units.","operationId":"set_spend_limit_v1_account_spend_limit_put","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/account/events":{"get":{"summary":"List Account Events","operationId":"list_account_events_v1_account_events_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/webhooks":{"get":{"summary":"List Webhooks","operationId":"list_webhooks_v1_webhooks_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"summary":"Create Webhook","operationId":"create_webhook_v1_webhooks_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/webhooks/{endpoint_id}":{"patch":{"summary":"Update Webhook","operationId":"update_webhook_v1_webhooks__endpoint_id__patch","parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string","title":"Endpoint Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"summary":"Delete Webhook","operationId":"delete_webhook_v1_webhooks__endpoint_id__delete","parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string","title":"Endpoint Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks/{endpoint_id}/rotate-secret":{"post":{"summary":"Rotate Webhook Secret","operationId":"rotate_webhook_secret_v1_webhooks__endpoint_id__rotate_secret_post","parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string","title":"Endpoint Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks/{endpoint_id}/test":{"post":{"summary":"Test Webhook","description":"Queue a test delivery for one specific endpoint.","operationId":"test_webhook_v1_webhooks__endpoint_id__test_post","parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string","title":"Endpoint Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks/{endpoint_id}/deliveries":{"get":{"summary":"List Webhook Deliveries","operationId":"list_webhook_deliveries_v1_webhooks__endpoint_id__deliveries_get","parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string","title":"Endpoint Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks/deliveries/{delivery_id}/redeliver":{"post":{"summary":"Redeliver Webhook","description":"Queue a new delivery from the payload of an existing one.","operationId":"redeliver_webhook_v1_webhooks_deliveries__delivery_id__redeliver_post","parameters":[{"name":"delivery_id","in":"path","required":true,"schema":{"type":"string","title":"Delivery Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/addresses":{"get":{"summary":"List Addresses","operationId":"list_addresses_v1_addresses_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"summary":"Create Address","operationId":"create_address_v1_addresses_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/addresses/validate":{"post":{"summary":"Validate Address","operationId":"validate_address_v1_addresses_validate_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/addresses/import":{"post":{"summary":"Import Addresses","operationId":"import_addresses_v1_addresses_import_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/addresses/{address_id}":{"get":{"summary":"Get Address","operationId":"get_address_v1_addresses__address_id__get","parameters":[{"name":"address_id","in":"path","required":true,"schema":{"type":"string","title":"Address Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"summary":"Update Address","operationId":"update_address_v1_addresses__address_id__patch","parameters":[{"name":"address_id","in":"path","required":true,"schema":{"type":"string","title":"Address Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"summary":"Delete Address","operationId":"delete_address_v1_addresses__address_id__delete","parameters":[{"name":"address_id","in":"path","required":true,"schema":{"type":"string","title":"Address Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/parcel-presets":{"get":{"summary":"List Presets","operationId":"list_presets_v1_parcel_presets_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"summary":"Create Preset","operationId":"create_preset_v1_parcel_presets_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/parcel-presets/{preset_id}":{"patch":{"summary":"Update Preset","operationId":"update_preset_v1_parcel_presets__preset_id__patch","parameters":[{"name":"preset_id","in":"path","required":true,"schema":{"type":"string","title":"Preset Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"summary":"Delete Preset","operationId":"delete_preset_v1_parcel_presets__preset_id__delete","parameters":[{"name":"preset_id","in":"path","required":true,"schema":{"type":"string","title":"Preset Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/shipment-templates":{"get":{"summary":"List Templates","operationId":"list_templates_v1_shipment_templates_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"summary":"Create Template","operationId":"create_template_v1_shipment_templates_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/shipment-templates/{template_id}/expand":{"get":{"summary":"Expand Template","operationId":"expand_template_v1_shipment_templates__template_id__expand_get","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string","title":"Template Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/shipment-templates/{template_id}":{"patch":{"summary":"Update Template","operationId":"update_template_v1_shipment_templates__template_id__patch","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string","title":"Template Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"summary":"Delete Template","operationId":"delete_template_v1_shipment_templates__template_id__delete","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string","title":"Template Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/hs-codes":{"get":{"summary":"Hs Codes","operationId":"hs_codes_v1_hs_codes_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/wallet/promo":{"post":{"summary":"Redeem Promo","operationId":"redeem_promo_v1_wallet_promo_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/wallet/grants":{"get":{"summary":"List Grants","operationId":"list_grants_v1_wallet_grants_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/promo/check":{"post":{"summary":"Check Promo","description":"{code, amount, currency} → the discount the code gives on that label price.\nNothing is reserved; the label request re-checks the code with the real price.","operationId":"check_promo_v1_promo_check_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/referral":{"get":{"summary":"Referral Stats","operationId":"referral_stats_v1_referral_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/referral/history":{"get":{"summary":"Referral History","operationId":"referral_history_v1_referral_history_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/auth/totp":{"post":{"summary":"Totp Login","description":"Resolve a login step-up challenge with a TOTP or recovery code.\n\nPublic: the caller has no session yet (the magic-link verify withheld it).\nOn success mints an aal=2 session and sets the cookie. Reports\n`codes_remaining` only when a recovery code was consumed.","operationId":"totp_login_v1_auth_totp_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/auth/factors":{"get":{"summary":"List Factors","operationId":"list_factors_v1_auth_factors_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"summary":"Begin Factor","operationId":"begin_factor_v1_auth_factors_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/auth/factors/{factor_id}/confirm":{"post":{"summary":"Confirm Factor","description":"Verify the first code, activate the factor, return the 8 recovery codes.\n\nA valid code is a fresh proof of possession, so the session is elevated to\naal=2 — the user can immediately manage the factor without a second prompt.","operationId":"confirm_factor_v1_auth_factors__factor_id__confirm_post","parameters":[{"name":"factor_id","in":"path","required":true,"schema":{"type":"string","title":"Factor Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/factors/{factor_id}":{"delete":{"summary":"Delete Factor","operationId":"delete_factor_v1_auth_factors__factor_id__delete","parameters":[{"name":"factor_id","in":"path","required":true,"schema":{"type":"string","title":"Factor Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/factors/{factor_id}/recovery-codes":{"get":{"summary":"List Recovery Codes","operationId":"list_recovery_codes_v1_auth_factors__factor_id__recovery_codes_get","parameters":[{"name":"factor_id","in":"path","required":true,"schema":{"type":"string","title":"Factor Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"summary":"Regenerate Recovery Codes","operationId":"regenerate_recovery_codes_v1_auth_factors__factor_id__recovery_codes_post","parameters":[{"name":"factor_id","in":"path","required":true,"schema":{"type":"string","title":"Factor Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/integrations/bookkeeping":{"get":{"summary":"List Bookkeeping","operationId":"list_bookkeeping_v1_integrations_bookkeeping_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/integrations/bookkeeping/connect":{"get":{"summary":"Connect Bookkeeping","operationId":"connect_bookkeeping_v1_integrations_bookkeeping_connect_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/integrations/bookkeeping/callback":{"get":{"summary":"Callback Bookkeeping","operationId":"callback_bookkeeping_v1_integrations_bookkeeping_callback_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/integrations/bookkeeping/{provider}/settings":{"patch":{"summary":"Update Bookkeeping Settings","operationId":"update_bookkeeping_settings_v1_integrations_bookkeeping__provider__settings_patch","parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string","title":"Provider"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/integrations/bookkeeping/{provider}":{"delete":{"summary":"Disconnect Bookkeeping","operationId":"disconnect_bookkeeping_v1_integrations_bookkeeping__provider__delete","parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string","title":"Provider"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/integrations/bookkeeping/{provider}/pushes":{"get":{"summary":"List Bookkeeping Pushes","operationId":"list_bookkeeping_pushes_v1_integrations_bookkeeping__provider__pushes_get","parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string","title":"Provider"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/integrations/bookkeeping/pushes/{push_id}/retry":{"post":{"summary":"Retry Bookkeeping Push","operationId":"retry_bookkeeping_push_v1_integrations_bookkeeping_pushes__push_id__retry_post","parameters":[{"name":"push_id","in":"path","required":true,"schema":{"type":"string","title":"Push Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/integrations/webshops":{"get":{"summary":"List Webshops","operationId":"list_webshops_v1_integrations_webshops_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/integrations/shopify/connect":{"get":{"summary":"Connect Shopify","operationId":"connect_shopify_v1_integrations_shopify_connect_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/integrations/shopify/callback":{"get":{"summary":"Callback Shopify","operationId":"callback_shopify_v1_integrations_shopify_callback_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/integrations/woocommerce":{"post":{"summary":"Connect Woocommerce","operationId":"connect_woocommerce_v1_integrations_woocommerce_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/integrations/webshops/{connection_id}":{"get":{"summary":"Get Webshop","operationId":"get_webshop_v1_integrations_webshops__connection_id__get","parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","title":"Connection Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"summary":"Update Webshop","operationId":"update_webshop_v1_integrations_webshops__connection_id__patch","parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","title":"Connection Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"summary":"Disconnect Webshop","operationId":"disconnect_webshop_v1_integrations_webshops__connection_id__delete","parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","title":"Connection Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/integrations/webshops/{connection_id}/sync":{"post":{"summary":"Sync Webshop","operationId":"sync_webshop_v1_integrations_webshops__connection_id__sync_post","parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","title":"Connection Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/integrations/webshops/{connection_id}/orders":{"get":{"summary":"List Webshop Orders","operationId":"list_webshop_orders_v1_integrations_webshops__connection_id__orders_get","parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","title":"Connection Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/integrations/shopify/webhook/{connection_id}":{"post":{"summary":"Shopify Webhook","operationId":"shopify_webhook_v1_integrations_shopify_webhook__connection_id__post","parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","title":"Connection Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/bulk-jobs":{"get":{"summary":"List Bulk Jobs","operationId":"list_bulk_jobs_v1_bulk_jobs_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"summary":"Create Bulk Job","operationId":"create_bulk_job_v1_bulk_jobs_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/bulk-jobs/{job_id}":{"get":{"summary":"Get Bulk Job","operationId":"get_bulk_job_v1_bulk_jobs__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/bulk-jobs/{job_id}/confirm":{"post":{"summary":"Confirm Bulk Job","operationId":"confirm_bulk_job_v1_bulk_jobs__job_id__confirm_post","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/bulk-jobs/{job_id}/cancel":{"post":{"summary":"Cancel Bulk Job","operationId":"cancel_bulk_job_v1_bulk_jobs__job_id__cancel_post","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/labels/{label_id}/return":{"post":{"summary":"Create a return label for an existing order","description":"Engine-gated (ENGINE_RETURNS). Builds a return shipment from the original order — from/to swapped — and charges the caller through the normal hold→mint→capture flow. Responds 501 not_available_yet until the feature is on.","operationId":"create_return_label_v1_labels__label_id__return_post","parameters":[{"name":"label_id","in":"path","required":true,"schema":{"type":"string","title":"Label Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/public/tracking/{token}":{"get":{"summary":"Public branded shipment timeline","description":"Token-authenticated (opaque trk_), no login, no PII. Empty / sandbox shipments carry an empty timeline (the page shows 'Tracking not available yet').","operationId":"public_tracking_v1_public_tracking__token__get","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/shipments/{ref}/events":{"get":{"summary":"Owner shipment timeline","description":"The account's own PII-free carrier timeline for a shipment.","operationId":"shipment_events_v1_shipments__ref__events_get","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","title":"Ref"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/shipments/{ref}/notifications":{"get":{"summary":"Read receiver notification opt-in for a shipment","operationId":"get_notifications_v1_shipments__ref__notifications_get","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","title":"Ref"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"summary":"Set receiver notification opt-in for a shipment","operationId":"put_notifications_v1_shipments__ref__notifications_put","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","title":"Ref"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account/exceptions":{"get":{"summary":"Shipments needing attention (exception inbox)","operationId":"list_exceptions_v1_account_exceptions_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/account/exceptions/{order_id}/resolve":{"post":{"summary":"Mark a shipment exception as handled","operationId":"resolve_exception_v1_account_exceptions__order_id__resolve_post","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account/branding":{"get":{"summary":"Read the account's public branding","operationId":"get_branding_v1_account_branding_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"put":{"summary":"Update the account's public branding (no logo upload)","description":"Session-only. Logo UPLOAD is not built here (owner decision #6); a logo_path in the body is ignored.","operationId":"put_branding_v1_account_branding_put","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/account/analytics":{"get":{"summary":"Account Analytics","operationId":"account_analytics_v1_account_analytics_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/exports/analytics.csv":{"get":{"summary":"Export Analytics Csv","operationId":"export_analytics_csv_v1_exports_analytics_csv_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/support/cases":{"get":{"summary":"List Cases","operationId":"list_cases_v1_support_cases_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"summary":"Create Case","operationId":"create_case_v1_support_cases_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/support/cases/{case_id}":{"get":{"summary":"Get Case","operationId":"get_case_v1_support_cases__case_id__get","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","title":"Case Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/support/cases/{case_id}/messages":{"post":{"summary":"Add Message","operationId":"add_message_v1_support_cases__case_id__messages_post","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","title":"Case Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/support/cases/{case_id}/attachments":{"post":{"summary":"Add Attachment","operationId":"add_attachment_v1_support_cases__case_id__attachments_post","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","title":"Case Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/labels/{label_id}/claims":{"post":{"summary":"Open Claim","operationId":"open_claim_v1_labels__label_id__claims_post","parameters":[{"name":"label_id","in":"path","required":true,"schema":{"type":"string","title":"Label Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/claims":{"get":{"summary":"List Claims","operationId":"list_claims_v1_claims_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/claims/{claim_id}":{"get":{"summary":"Get Claim","operationId":"get_claim_v1_claims__claim_id__get","parameters":[{"name":"claim_id","in":"path","required":true,"schema":{"type":"string","title":"Claim Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/claims/{claim_id}/messages":{"post":{"summary":"Add Claim Message","operationId":"add_claim_message_v1_claims__claim_id__messages_post","parameters":[{"name":"claim_id","in":"path","required":true,"schema":{"type":"string","title":"Claim Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/public/returns/{token}":{"get":{"summary":"Public return portal — original shipment + portal config","operationId":"public_return_view_v1_public_returns__token__get","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"summary":"Submit a self-service return request","operationId":"public_return_submit_v1_public_returns__token__post","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account/returns-portal":{"get":{"summary":"Get Returns Portal","operationId":"get_returns_portal_v1_account_returns_portal_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"put":{"summary":"Put Returns Portal","operationId":"put_returns_portal_v1_account_returns_portal_put","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/returns":{"get":{"summary":"List Returns","operationId":"list_returns_v1_returns_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/returns/{request_id}":{"get":{"summary":"Get Return","operationId":"get_return_v1_returns__request_id__get","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/returns/{request_id}/approve":{"post":{"summary":"Approve Return","operationId":"approve_return_v1_returns__request_id__approve_post","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/returns/{request_id}/reject":{"post":{"summary":"Reject Return","operationId":"reject_return_v1_returns__request_id__reject_post","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/returns/{request_id}/issue-label":{"post":{"summary":"Issue Return Label","operationId":"issue_return_label_v1_returns__request_id__issue_label_post","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/carriers":{"get":{"summary":"List public carriers and where they're offered","operationId":"carriers_v1_carriers_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/CarrierInfo"},"type":"array","title":"Response Carriers V1 Carriers Get"}}}}}}},"/v1/quotes":{"post":{"summary":"Quote a shipment — carrier + price preview","description":"Returns live rates in carrier terms, in the requested `currency`. Honors a concrete `carrier`/`service` filter; rules (cheapest/fastest) return the full list, cheapest first. Each rate carries `service_type` (home | parcelshop | business) and a `service_id` to send back on POST /v1/labels.","operationId":"quotes_v1_quotes_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/labels/{label_id}":{"get":{"summary":"Read a label/order back","operationId":"get_label_v1_labels__label_id__get","parameters":[{"name":"label_id","in":"path","required":true,"schema":{"type":"string","title":"Label Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/labels/{label_id}/cancel":{"post":{"summary":"Cancel (void) a label","description":"Cancels the label: the order is voided and the label document is revoked; the label is also voided at the carrier when the carrier allows it. A label that was already handed to the carrier cannot be cancelled (409 not_cancellable).","operationId":"cancel_label_v1_labels__label_id__cancel_post","parameters":[{"name":"label_id","in":"path","required":true,"schema":{"type":"string","title":"Label Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/shipments/{ref}":{"get":{"summary":"Track a shipment","description":"Accepts a tracking number, order id or label id — for labels bought here. Sandbox labels have no tracking.","operationId":"track_v1_shipments__ref__get","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","title":"Ref"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/addresses/parse":{"post":{"summary":"Extract postal addresses from text or an image","description":"**Best-effort — keep off the critical buy path.** AI extraction: send `{\"text\": …}` or `{\"image\": <base64>, \"media_type\": \"image/png\"}`. Returns `{addresses: [...]}` in the standard address shape (country as ISO-2). Depends on an external AI provider and may return `503` (not configured), `429` (rate limited), or `502` (provider error) independently of the rest of /v1 — always handle these as soft failures in your flow.","operationId":"parse_address_v1_addresses_parse_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"Address":{"properties":{"name":{"type":"string","minLength":1,"title":"Name","description":"Contact or recipient name"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Company, if business address"},"address_1":{"type":"string","minLength":1,"title":"Address 1","description":"Street address"},"address_2":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address 2","description":"Apartment, suite, etc."},"zip":{"type":"string","minLength":1,"title":"Zip","description":"Postal code"},"city":{"type":"string","minLength":1,"title":"City","description":"City or town"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State","description":"State/province — required for US, CA, AU destinations (the engine can derive it from the postal code if omitted)"},"country":{"type":"string","maxLength":2,"minLength":2,"title":"Country","description":"ISO 3166-1 alpha-2, e.g. DK"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Contact email"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone","description":"Contact phone, intl format"}},"additionalProperties":false,"type":"object","required":["name","address_1","zip","city","country"],"title":"Address","description":"From/To/Return address (fc.js From/To/Return groups — same shape)."},"Billing":{"properties":{"name":{"type":"string","minLength":1,"title":"Name"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name"},"email":{"type":"string","minLength":3,"title":"Email","description":"Receipt + payment link go here"},"address_1":{"type":"string","minLength":1,"title":"Address 1"},"zip":{"type":"string","minLength":1,"title":"Zip"},"city":{"type":"string","minLength":1,"title":"City"},"country":{"type":"string","maxLength":2,"minLength":2,"title":"Country"},"vat_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vat Number","description":"EU VAT number (B2B reverse charge)"}},"additionalProperties":false,"type":"object","required":["name","email","address_1","zip","city","country"],"title":"Billing","description":"Guest billing block (fc.js Billing group). Clients are billed on account."},"CarrierInfo":{"properties":{"carrier":{"type":"string","title":"Carrier"},"services":{"items":{"type":"string"},"type":"array","title":"Services"},"routes":{"type":"string","title":"Routes","description":"Human description of where this carrier is offered"},"rules":{"items":{"type":"string"},"type":"array","title":"Rules","description":"Which rules (cheapest/fastest) can resolve to it"}},"type":"object","required":["carrier","services","routes"],"title":"CarrierInfo","description":"One entry of GET /v1/carriers — honest per-route availability."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Insurance":{"properties":{"amount":{"type":"number","exclusiveMinimum":0.0,"title":"Amount","description":"Insured value in the shipment currency"}},"additionalProperties":false,"type":"object","required":["amount"],"title":"Insurance"},"LabelRequest":{"properties":{"sandbox":{"type":"boolean","title":"Sandbox","description":"End-to-end test mode (carrier test APIs, nothing persisted)","default":false},"currency":{"type":"string","enum":["DKK","EUR","USD","GBP","SEK","NOK"],"title":"Currency","description":"Display and charge currency — prices are quoted and charged in this currency (DKK default)","default":"DKK"},"units":{"type":"string","enum":["metric","imperial"],"title":"Units","default":"metric"},"account_type":{"type":"string","enum":["guest","client"],"title":"Account Type","default":"guest"},"client_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Id","description":"Account key (client) or billing email (guest — derived from billing.email if omitted)"},"client_reference":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Reference","description":"Your internal reference"},"cost_center":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cost Center","description":"Cost allocation tag"},"client_logo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Logo","description":"PNG/SVG URL printed instead of the carrier wordmark"},"event_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Url","description":"Webhook for status events"},"billing":{"anyOf":[{"$ref":"#/components/schemas/Billing"},{"type":"null"}],"description":"Required for guests at payment time; omitted for account clients"},"from_address":{"$ref":"#/components/schemas/Address"},"to_address":{"$ref":"#/components/schemas/Address"},"is_return":{"type":"boolean","title":"Is Return","description":"Swap direction: a return label","default":false},"return_address":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}],"description":"Overrides the destination for returns"},"carrier":{"anyOf":[{"type":"string","enum":["cheapest","fastest"]},{"type":"string","enum":["postnord","gls","dao","dhl","bring","ups","evri","dpd","royal mail","dhl ecommerce","fedex","postnl","asendia","dfm"]}],"title":"Carrier","description":"Rule (cheapest/fastest) or a carrier. On quotes the concrete carrier filters the answer; on label creation it is ADVISORY today — the engine routes by service + destination.","default":"cheapest"},"service":{"type":"string","enum":["home","parcelshop","business"],"title":"Service","default":"parcelshop"},"service_id":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Service Id","description":"The service_id of the quoted rate to book (from POST /v1/quotes); the label is priced on exactly that rate"},"qr_code":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Qr Code","description":"Add a QR/DataMatrix code (not yet honored)"},"saturday_delivery":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Saturday Delivery","description":"Not yet honored"},"signature_required":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Signature Required","description":"Not yet honored"},"insurance":{"anyOf":[{"$ref":"#/components/schemas/Insurance"},{"type":"null"}],"description":"Not yet honored — do not charge"},"notifications":{"anyOf":[{"$ref":"#/components/schemas/Notifications"},{"type":"null"}],"description":"Not yet honored"},"shipment_reference":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shipment Reference","description":"Printed on the label"},"shipment_reference_2":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shipment Reference 2"},"payment_mode":{"anyOf":[{"type":"string","enum":["link","prepaid","issue_now"]},{"type":"null"}],"title":"Payment Mode","description":"How this label is paid: link = pay-link, PDF released on payment (guest default) · prepaid = account balance (client default) · issue_now = PDF immediately, auto-void if unpaid in 60 min"},"payment_method":{"anyOf":[{"type":"string","enum":["applepay","creditcard","googlepay"]},{"type":"null"}],"title":"Payment Method","description":"Preselect the checkout method for link / issue_now (googlepay runs through the card checkout)"},"promo_code":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Promo Code","description":"A checkout promo code — the discount comes off the label price (card / pay-later checkout)."},"card_token":{"anyOf":[{"type":"string","pattern":"^tkn_[A-Za-z0-9]{4,64}$"},{"type":"null"}],"title":"Card Token","description":"A card token from the embedded card fields (payment_method creditcard) — card data never reaches 321label"},"googlepay_token":{"anyOf":[{"type":"string","maxLength":20000},{"type":"null"}],"title":"Googlepay Token","description":"The Google Pay payment token from the on-page Google Pay sheet (payment_method googlepay), passed through to the payment provider"},"applepay_token":{"anyOf":[{"type":"string","maxLength":20000},{"type":"null"}],"title":"Applepay Token","description":"The Apple Pay payment token from the on-page Apple Pay sheet (payment_method applepay), passed through to the payment provider"},"parcels":{"items":{"$ref":"#/components/schemas/Parcel"},"type":"array","minItems":1,"title":"Parcels"}},"additionalProperties":false,"type":"object","required":["from_address","to_address","parcels"],"title":"LabelRequest","description":"The one request shape — UI, REST and MCP all build exactly this."},"Notifications":{"properties":{"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Status emails to this address"},"sms":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sms","description":"Status SMS to this number"}},"additionalProperties":false,"type":"object","title":"Notifications"},"Parcel":{"properties":{"weight":{"type":"number","exclusiveMinimum":0.0,"title":"Weight","description":"kg (metric) or lb (imperial)"},"length":{"type":"number","exclusiveMinimum":0.0,"title":"Length","description":"cm (metric) or in (imperial)"},"width":{"type":"number","exclusiveMinimum":0.0,"title":"Width","description":"cm (metric) or in (imperial)"},"height":{"type":"number","exclusiveMinimum":0.0,"title":"Height","description":"cm (metric) or in (imperial)"},"products":{"anyOf":[{"items":{"$ref":"#/components/schemas/Product"},"type":"array"},{"type":"null"}],"title":"Products","description":"Line items — required for customs outside the EU"}},"additionalProperties":false,"type":"object","required":["weight","length","width","height"],"title":"Parcel","description":"Physical parcel (fc.js Parcels group). Dimensions in the global `units`."},"Product":{"properties":{"description":{"type":"string","minLength":1,"title":"Description","description":"What the item is"},"sku":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sku"},"quantity":{"type":"integer","minimum":1.0,"title":"Quantity","default":1},"value":{"type":"number","minimum":0.0,"title":"Value","description":"Unit price in the shipment currency"},"hs_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hs Code","description":"Harmonized tariff code"},"origin_country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origin Country","description":"ISO 3166-1 alpha-2"}},"additionalProperties":false,"type":"object","required":["description","value"],"title":"Product","description":"Line item inside a parcel (fc.js Products group) — drives customs."},"QuoteRequest":{"properties":{"sandbox":{"type":"boolean","title":"Sandbox","default":false},"currency":{"type":"string","enum":["DKK","EUR","USD","GBP","SEK","NOK"],"title":"Currency","description":"Currency for quoted prices (DKK default; EUR, USD, GBP, SEK, NOK)","default":"DKK"},"units":{"type":"string","enum":["metric","imperial"],"title":"Units","default":"metric"},"from_address":{"$ref":"#/components/schemas/Address"},"to_address":{"$ref":"#/components/schemas/Address"},"parcels":{"items":{"$ref":"#/components/schemas/Parcel"},"type":"array","minItems":1,"title":"Parcels"},"carrier":{"anyOf":[{"type":"string","enum":["cheapest","fastest"]},{"type":"string","enum":["postnord","gls","dao","dhl","bring","ups","evri","dpd","royal mail","dhl ecommerce","fedex","postnl","asendia","dfm"]},{"type":"null"}],"title":"Carrier","description":"Filter to one rule/carrier"},"service":{"anyOf":[{"type":"string","enum":["home","parcelshop","business"]},{"type":"null"}],"title":"Service"},"sort":{"type":"string","enum":["cheapest","fastest"],"title":"Sort","description":"Rate ordering: cheapest (default) | fastest","default":"cheapest"}},"additionalProperties":false,"type":"object","required":["from_address","to_address","parcels"],"title":"QuoteRequest"},"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"}}}}