{
  "openapi": "3.1.0",
  "info": {
    "title": "Octoship API",
    "version": "1.0.0",
    "description": "Rates, labels, tracking and more. All amounts are integers in minor units."
  },
  "servers": [
    {
      "url": "https://api.octoship.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Secret API key: `Authorization: Bearer os_live_…` or `os_test_…`"
      },
      "session": {
        "type": "apiKey",
        "in": "cookie",
        "name": "octoship.session_token"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "invalid_request",
                  "authentication_error",
                  "permission_error",
                  "not_found",
                  "conflict",
                  "idempotency_error",
                  "unprocessable",
                  "rate_limit_error",
                  "carrier_error",
                  "service_unavailable",
                  "api_error"
                ]
              },
              "code": {
                "type": "string",
                "example": "shipment_not_found"
              },
              "message": {
                "type": "string"
              },
              "request_id": {
                "type": "string",
                "example": "req_0193a5c46f7e7d4b9c1a3e2f1a0b9c8d"
              },
              "details": {}
            },
            "required": [
              "type",
              "code",
              "message",
              "request_id"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "ActiveOrganizationSet": {
        "type": "object",
        "properties": {
          "organization_id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          }
        },
        "required": [
          "organization_id"
        ]
      },
      "Invite": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "invite"
            ]
          },
          "organization_id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "role": {
            "$ref": "#/components/schemas/Role"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "accepted",
              "rejected",
              "canceled",
              "expired"
            ]
          },
          "invited_by": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "organization_id",
          "email",
          "role",
          "status",
          "invited_by",
          "expires_at",
          "created_at"
        ]
      },
      "Role": {
        "type": "string",
        "enum": [
          "captain",
          "first_mate",
          "deckhand"
        ],
        "description": "captain: everything · first_mate: everything except billing & crew · deckhand: ship & print only"
      },
      "InviteCreate": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email"
          },
          "role": {
            "$ref": "#/components/schemas/Role"
          }
        },
        "required": [
          "email",
          "role"
        ]
      },
      "Me": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "me"
            ]
          },
          "user": {
            "$ref": "#/components/schemas/User"
          },
          "memberships": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "organization": {
                  "$ref": "#/components/schemas/Organization"
                },
                "role": {
                  "$ref": "#/components/schemas/Role"
                }
              },
              "required": [
                "organization",
                "role"
              ]
            }
          },
          "active_organization_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          }
        },
        "required": [
          "object",
          "user",
          "memberships",
          "active_organization_id"
        ]
      },
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "user"
            ]
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "name": {
            "type": "string"
          },
          "image": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "email_verified": {
            "type": "boolean"
          },
          "two_factor_enabled": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "email",
          "name",
          "image",
          "email_verified",
          "two_factor_enabled",
          "created_at"
        ]
      },
      "Organization": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "organization"
            ]
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "logo": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "origin_country": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "description": "Ship-from country; drives couriers, currency and units",
            "example": "US"
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "description": "ISO 4217",
            "example": "USD"
          },
          "unit_system": {
            "type": "string",
            "enum": [
              "imperial",
              "metric"
            ]
          },
          "timezone": {
            "type": "string"
          },
          "mode": {
            "type": "string",
            "enum": [
              "test",
              "live"
            ],
            "description": "`test` until the store goes live"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "name",
          "slug",
          "logo",
          "origin_country",
          "currency",
          "unit_system",
          "timezone",
          "mode",
          "created_at",
          "updated_at"
        ]
      },
      "Membership": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "membership"
            ]
          },
          "organization_id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "user": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "UUIDv7",
                "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
              },
              "email": {
                "type": "string",
                "format": "email"
              },
              "name": {
                "type": "string"
              },
              "image": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uri"
              }
            },
            "required": [
              "id",
              "email",
              "name",
              "image"
            ]
          },
          "role": {
            "$ref": "#/components/schemas/Role"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "organization_id",
          "user",
          "role",
          "created_at"
        ]
      },
      "MembershipUpdate": {
        "type": "object",
        "properties": {
          "role": {
            "$ref": "#/components/schemas/Role"
          }
        },
        "required": [
          "role"
        ]
      },
      "OrganizationCreate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "origin_country": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "description": "ISO 3166-1 alpha-2",
            "example": "US"
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "description": "Defaults to the origin's currency",
            "example": "USD"
          },
          "unit_system": {
            "type": "string",
            "enum": [
              "imperial",
              "metric"
            ]
          },
          "timezone": {
            "type": "string",
            "maxLength": 64
          }
        },
        "required": [
          "name",
          "origin_country"
        ]
      },
      "OrganizationUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "timezone": {
            "type": "string",
            "maxLength": 64
          },
          "unit_system": {
            "type": "string",
            "enum": [
              "imperial",
              "metric"
            ]
          },
          "logo": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          }
        },
        "description": "Ship-from country and currency are fixed after creation"
      },
      "Catalog": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "catalog"
            ]
          },
          "origin": {
            "$ref": "#/components/schemas/Origin"
          },
          "couriers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Courier"
            }
          },
          "services": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Service"
            }
          }
        },
        "required": [
          "object",
          "origin",
          "couriers",
          "services"
        ]
      },
      "Origin": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "origin"
            ]
          },
          "code": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "description": "ISO 3166-1 alpha-2",
            "example": "US"
          },
          "name": {
            "type": "string"
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "description": "ISO 4217",
            "example": "USD"
          },
          "unit_system": {
            "type": "string",
            "enum": [
              "imperial",
              "metric"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "live",
              "coming_soon",
              "disabled"
            ]
          },
          "courier_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Courier slugs available from this origin, in display order"
          }
        },
        "required": [
          "object",
          "code",
          "name",
          "currency",
          "unit_system",
          "status",
          "courier_ids"
        ]
      },
      "Courier": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "courier"
            ]
          },
          "id": {
            "type": "string",
            "description": "Stable Octoship courier slug",
            "example": "usps"
          },
          "name": {
            "type": "string"
          },
          "color": {
            "type": "string",
            "pattern": "^#[0-9a-fA-F]{6}$",
            "description": "Brand color"
          },
          "kind": {
            "type": "string",
            "enum": [
              "postal",
              "express",
              "parcel",
              "cross-border"
            ]
          },
          "blurb": {
            "type": "string"
          },
          "logo_url": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "object",
          "id",
          "name",
          "color",
          "kind",
          "blurb",
          "logo_url"
        ]
      },
      "Service": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "service"
            ]
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "courier_id": {
            "type": "string"
          },
          "origin": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "description": "ISO 3166-1 alpha-2",
            "example": "US"
          },
          "code": {
            "type": "string",
            "description": "Stable Octoship service code",
            "example": "usps_ground_advantage"
          },
          "name": {
            "type": "string"
          },
          "scope": {
            "type": "string",
            "enum": [
              "domestic",
              "international"
            ]
          },
          "transit_days_min": {
            "type": [
              "integer",
              "null"
            ]
          },
          "transit_days_max": {
            "type": [
              "integer",
              "null"
            ]
          },
          "transit_label": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "object",
          "id",
          "courier_id",
          "origin",
          "code",
          "name",
          "scope",
          "transit_days_min",
          "transit_days_max",
          "transit_label"
        ]
      },
      "OriginList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Origin"
            }
          }
        },
        "required": [
          "object",
          "data"
        ]
      },
      "Address": {
        "type": "object",
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "default": null
          },
          "company": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "default": null
          },
          "line1": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "line2": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 200,
            "default": null
          },
          "city": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "region": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "default": null,
            "description": "State / province / county"
          },
          "postal_code": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 20,
            "default": null
          },
          "country": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "description": "ISO 3166-1 alpha-2",
            "example": "US"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 40,
            "default": null
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email",
            "default": null
          },
          "residential": {
            "type": [
              "boolean",
              "null"
            ],
            "default": null
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "address"
            ]
          },
          "label": {
            "type": [
              "string",
              "null"
            ]
          },
          "is_default_from": {
            "type": "boolean"
          },
          "validated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "line1",
          "city",
          "country",
          "id",
          "object",
          "label",
          "is_default_from",
          "validated_at",
          "created_at"
        ]
      },
      "AddressCreate": {
        "type": "object",
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "default": null
          },
          "company": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "default": null
          },
          "line1": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "line2": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 200,
            "default": null
          },
          "city": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "region": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "default": null,
            "description": "State / province / county"
          },
          "postal_code": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 20,
            "default": null
          },
          "country": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "description": "ISO 3166-1 alpha-2",
            "example": "US"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 40,
            "default": null
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email",
            "default": null
          },
          "residential": {
            "type": [
              "boolean",
              "null"
            ],
            "default": null
          },
          "label": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 60,
            "default": null
          },
          "is_default_from": {
            "type": "boolean",
            "default": false
          }
        },
        "required": [
          "line1",
          "city",
          "country"
        ]
      },
      "AddressList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Address"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
        ]
      },
      "AddressUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100
          },
          "company": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100
          },
          "line1": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "line2": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 200
          },
          "city": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "region": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100
          },
          "postal_code": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 20
          },
          "country": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "description": "ISO 3166-1 alpha-2",
            "example": "US"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 40
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email"
          },
          "residential": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "label": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 60
          },
          "is_default_from": {
            "type": "boolean"
          }
        }
      },
      "CustomsDeclaration": {
        "type": "object",
        "properties": {
          "contents_type": {
            "type": "string",
            "enum": [
              "merchandise",
              "gift",
              "documents",
              "sample",
              "return",
              "other"
            ]
          },
          "contents_explanation": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 200,
            "default": null
          },
          "incoterm": {
            "type": "string",
            "enum": [
              "DDP",
              "DDU"
            ],
            "default": "DDU"
          },
          "non_delivery": {
            "type": "string",
            "enum": [
              "return",
              "abandon"
            ],
            "default": "return"
          },
          "invoice_number": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 50,
            "default": null
          },
          "eel_pfc": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 50,
            "default": null
          },
          "signer": {
            "type": "string",
            "maxLength": 100
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomsItem"
            },
            "minItems": 1,
            "maxItems": 100
          }
        },
        "required": [
          "contents_type",
          "signer",
          "items"
        ]
      },
      "CustomsItem": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "quantity": {
            "type": "integer",
            "exclusiveMinimum": 0
          },
          "value": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Minor units (e.g. cents)",
                "example": 412
              },
              "currency": {
                "type": "string",
                "pattern": "^[A-Z]{3}$",
                "description": "ISO 4217",
                "example": "USD"
              }
            },
            "required": [
              "amount",
              "currency"
            ],
            "description": "Value per unit"
          },
          "weight": {
            "type": "object",
            "properties": {
              "value": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 100000
              },
              "unit": {
                "type": "string",
                "enum": [
                  "oz",
                  "lb",
                  "g",
                  "kg"
                ]
              }
            },
            "required": [
              "value",
              "unit"
            ],
            "description": "Weight per unit"
          },
          "hs_code": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{6,10}$",
            "default": null
          },
          "origin_country": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "description": "ISO 3166-1 alpha-2",
            "example": "US"
          },
          "sku": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "default": null
          }
        },
        "required": [
          "description",
          "quantity",
          "value",
          "weight",
          "origin_country"
        ]
      },
      "Label": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "label"
            ]
          },
          "mode": {
            "$ref": "#/components/schemas/Mode"
          },
          "shipment_id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "rate_id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "status": {
            "type": "string",
            "enum": [
              "purchasing",
              "purchased",
              "void_requested",
              "voided",
              "refunded",
              "failed"
            ]
          },
          "tracking_number": {
            "type": [
              "string",
              "null"
            ]
          },
          "courier_id": {
            "type": "string"
          },
          "service_code": {
            "type": "string"
          },
          "price": {
            "$ref": "#/components/schemas/Money"
          },
          "format": {
            "type": "string",
            "enum": [
              "pdf",
              "png",
              "zpl"
            ]
          },
          "size": {
            "type": "string",
            "enum": [
              "4x6",
              "letter",
              "a4"
            ]
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Short-lived signed URL to the label file"
          },
          "tracker_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "purchased_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "voided_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "mode",
          "shipment_id",
          "rate_id",
          "status",
          "tracking_number",
          "courier_id",
          "service_code",
          "price",
          "format",
          "size",
          "url",
          "tracker_id",
          "purchased_at",
          "voided_at",
          "created_at"
        ]
      },
      "Mode": {
        "type": "string",
        "enum": [
          "test",
          "live"
        ]
      },
      "Money": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "integer",
            "description": "Minor units (e.g. cents)",
            "example": 412
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "description": "ISO 4217",
            "example": "USD"
          }
        },
        "required": [
          "amount",
          "currency"
        ]
      },
      "LabelCreate": {
        "type": "object",
        "properties": {
          "rate_id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "format": {
            "type": "string",
            "enum": [
              "pdf",
              "png",
              "zpl"
            ],
            "default": "pdf"
          },
          "size": {
            "type": "string",
            "enum": [
              "4x6",
              "letter",
              "a4"
            ],
            "default": "4x6"
          }
        },
        "required": [
          "rate_id"
        ]
      },
      "LabelList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Label"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
        ]
      },
      "PackagePreset": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "package_preset"
            ]
          },
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "box",
              "envelope",
              "poly_mailer",
              "tube",
              "flat_rate",
              "pallet",
              "other"
            ]
          },
          "dimensions": {
            "$ref": "#/components/schemas/Dimensions"
          },
          "weight": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "value": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 100000
              },
              "unit": {
                "type": "string",
                "enum": [
                  "oz",
                  "lb",
                  "g",
                  "kg"
                ]
              }
            },
            "required": [
              "value",
              "unit"
            ],
            "description": "Empty packaging weight, added to item weight"
          },
          "is_default": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "name",
          "type",
          "dimensions",
          "weight",
          "is_default",
          "created_at"
        ]
      },
      "Dimensions": {
        "type": [
          "object",
          "null"
        ],
        "properties": {
          "length": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 10000
          },
          "width": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 10000
          },
          "height": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 10000
          },
          "unit": {
            "type": "string",
            "enum": [
              "in",
              "cm"
            ]
          }
        },
        "required": [
          "length",
          "width",
          "height",
          "unit"
        ]
      },
      "PackagePresetCreate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60
          },
          "type": {
            "type": "string",
            "enum": [
              "box",
              "envelope",
              "poly_mailer",
              "tube",
              "flat_rate",
              "pallet",
              "other"
            ],
            "default": "box"
          },
          "dimensions": {
            "$ref": "#/components/schemas/Dimensions"
          },
          "weight": {
            "$ref": "#/components/schemas/Weight"
          },
          "is_default": {
            "type": "boolean",
            "default": false
          }
        },
        "required": [
          "name"
        ]
      },
      "Weight": {
        "type": [
          "object",
          "null"
        ],
        "properties": {
          "value": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 100000
          },
          "unit": {
            "type": "string",
            "enum": [
              "oz",
              "lb",
              "g",
              "kg"
            ]
          }
        },
        "default": null,
        "required": [
          "value",
          "unit"
        ],
        "description": "Stored exactly as entered; converted only when talking to carriers."
      },
      "PackagePresetList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PackagePreset"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
        ]
      },
      "PackagePresetUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60
          },
          "type": {
            "type": "string",
            "enum": [
              "box",
              "envelope",
              "poly_mailer",
              "tube",
              "flat_rate",
              "pallet",
              "other"
            ]
          },
          "dimensions": {
            "$ref": "#/components/schemas/Dimensions"
          },
          "weight": {
            "$ref": "#/components/schemas/Weight"
          },
          "is_default": {
            "type": "boolean"
          }
        }
      },
      "Parcel": {
        "type": "object",
        "properties": {
          "weight": {
            "$ref": "#/components/schemas/Weight"
          },
          "dimensions": {
            "$ref": "#/components/schemas/Dimensions"
          },
          "preset_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "default": null,
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          }
        },
        "required": [
          "weight"
        ]
      },
      "Rate": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "rate"
            ]
          },
          "shipment_id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "courier_id": {
            "type": "string"
          },
          "service_code": {
            "type": "string"
          },
          "service_name": {
            "type": "string"
          },
          "price": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Minor units (e.g. cents)",
                "example": 412
              },
              "currency": {
                "type": "string",
                "pattern": "^[A-Z]{3}$",
                "description": "ISO 4217",
                "example": "USD"
              }
            },
            "required": [
              "amount",
              "currency"
            ],
            "description": "What you pay"
          },
          "retail": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Minor units (e.g. cents)",
                "example": 412
              },
              "currency": {
                "type": "string",
                "pattern": "^[A-Z]{3}$",
                "description": "ISO 4217",
                "example": "USD"
              }
            },
            "required": [
              "amount",
              "currency"
            ],
            "description": "Carrier retail price, for 'you saved'"
          },
          "transit_days_min": {
            "type": [
              "integer",
              "null"
            ]
          },
          "transit_days_max": {
            "type": [
              "integer",
              "null"
            ]
          },
          "estimated_delivery_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "cheapest",
                "fastest",
                "best_value"
              ]
            }
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "shipment_id",
          "courier_id",
          "service_code",
          "service_name",
          "price",
          "retail",
          "transit_days_min",
          "transit_days_max",
          "estimated_delivery_at",
          "tags",
          "expires_at"
        ]
      },
      "RateMessage": {
        "type": "object",
        "properties": {
          "courier_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Null when the message isn't about one courier"
          },
          "code": {
            "type": "string",
            "example": "courier_unavailable"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "courier_id",
          "code",
          "message"
        ]
      },
      "RateQuote": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "rate_quote"
            ]
          },
          "shipment": {
            "$ref": "#/components/schemas/Shipment"
          },
          "rates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Rate"
            }
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RateMessage"
            }
          }
        },
        "required": [
          "object",
          "shipment",
          "rates",
          "messages"
        ]
      },
      "Shipment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "shipment"
            ]
          },
          "mode": {
            "$ref": "#/components/schemas/Mode"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "rated",
              "purchasing",
              "purchased",
              "voided",
              "failed"
            ]
          },
          "from_address": {
            "$ref": "#/components/schemas/AddressSnapshot"
          },
          "to_address": {
            "$ref": "#/components/schemas/AddressSnapshot"
          },
          "return_address": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AddressSnapshot"
              },
              {
                "type": [
                  "object",
                  "null"
                ]
              }
            ]
          },
          "parcel": {
            "$ref": "#/components/schemas/Parcel"
          },
          "options": {
            "$ref": "#/components/schemas/ShipmentOptions"
          },
          "customs": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CustomsDeclaration"
              },
              {
                "type": [
                  "object",
                  "null"
                ]
              }
            ]
          },
          "order_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "selected_rate_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "label_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "mode",
          "status",
          "from_address",
          "to_address",
          "return_address",
          "parcel",
          "options",
          "customs",
          "order_id",
          "selected_rate_id",
          "label_id",
          "metadata",
          "created_at",
          "updated_at"
        ]
      },
      "AddressSnapshot": {
        "type": "object",
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "default": null
          },
          "company": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "default": null
          },
          "line1": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "line2": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 200,
            "default": null
          },
          "city": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "region": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "default": null,
            "description": "State / province / county"
          },
          "postal_code": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 20,
            "default": null
          },
          "country": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "description": "ISO 3166-1 alpha-2",
            "example": "US"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 40,
            "default": null
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email",
            "default": null
          },
          "residential": {
            "type": [
              "boolean",
              "null"
            ],
            "default": null
          }
        },
        "required": [
          "line1",
          "city",
          "country"
        ]
      },
      "ShipmentOptions": {
        "type": "object",
        "properties": {
          "signature": {
            "type": "string",
            "enum": [
              "none",
              "standard",
              "adult"
            ],
            "default": "none"
          },
          "insurance": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Minor units (e.g. cents)",
                "example": 412
              },
              "currency": {
                "type": "string",
                "pattern": "^[A-Z]{3}$",
                "description": "ISO 4217",
                "example": "USD"
              }
            },
            "default": null,
            "required": [
              "amount",
              "currency"
            ],
            "description": "Declared value to insure"
          },
          "saturday_delivery": {
            "type": "boolean",
            "default": false
          },
          "reference": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "default": null
          }
        }
      },
      "Metadata": {
        "type": "object",
        "additionalProperties": {
          "type": "string",
          "maxLength": 500
        },
        "description": "Up to 50 string key/value pairs for your own use."
      },
      "ShipmentCreate": {
        "type": "object",
        "properties": {
          "from_address": {
            "type": "object",
            "properties": {
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 100,
                "default": null
              },
              "company": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 100,
                "default": null
              },
              "line1": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              },
              "line2": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 200,
                "default": null
              },
              "city": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "region": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 100,
                "default": null,
                "description": "State / province / county"
              },
              "postal_code": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 20,
                "default": null
              },
              "country": {
                "type": "string",
                "pattern": "^[A-Z]{2}$",
                "description": "ISO 3166-1 alpha-2",
                "example": "US"
              },
              "phone": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 40,
                "default": null
              },
              "email": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "email",
                "default": null
              },
              "residential": {
                "type": [
                  "boolean",
                  "null"
                ],
                "default": null
              }
            },
            "required": [
              "line1",
              "city",
              "country"
            ],
            "description": "Defaults to the store's default ship-from address"
          },
          "to_address": {
            "$ref": "#/components/schemas/AddressSnapshot"
          },
          "return_address": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AddressSnapshot"
              },
              {
                "type": [
                  "object",
                  "null"
                ]
              }
            ]
          },
          "parcel": {
            "$ref": "#/components/schemas/Parcel"
          },
          "options": {
            "$ref": "#/components/schemas/ShipmentOptions"
          },
          "customs": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CustomsDeclaration"
              },
              {
                "type": [
                  "object",
                  "null"
                ]
              }
            ]
          },
          "order_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "default": null,
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          }
        },
        "required": [
          "to_address",
          "parcel"
        ]
      },
      "ShipmentList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Shipment"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
        ]
      },
      "Tracker": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "tracker"
            ]
          },
          "mode": {
            "$ref": "#/components/schemas/Mode"
          },
          "tracking_number": {
            "type": "string"
          },
          "courier_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "unknown",
              "label_created",
              "in_transit",
              "out_for_delivery",
              "delivered",
              "exception",
              "returned"
            ]
          },
          "shipment_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "label_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "estimated_delivery_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "delivered_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "public_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Branded tracking page"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TrackingEvent"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "mode",
          "tracking_number",
          "courier_id",
          "status",
          "shipment_id",
          "label_id",
          "estimated_delivery_at",
          "delivered_at",
          "public_url",
          "events",
          "created_at",
          "updated_at"
        ]
      },
      "TrackingEvent": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "tracking_event"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "unknown",
              "label_created",
              "in_transit",
              "out_for_delivery",
              "delivered",
              "exception",
              "returned"
            ]
          },
          "description": {
            "type": "string"
          },
          "location": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "city": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "region": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "country": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^[A-Z]{2}$",
                "description": "ISO 3166-1 alpha-2",
                "example": "US"
              },
              "postal_code": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "city",
              "region",
              "country",
              "postal_code"
            ]
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "status",
          "description",
          "location",
          "occurred_at"
        ]
      },
      "TrackerList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Tracker"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
        ]
      },
      "AppliedShippingRule": {
        "type": "object",
        "properties": {
          "rule_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Null when no rule matched and the default applies",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "version": {
            "type": [
              "integer",
              "null"
            ],
            "exclusiveMinimum": 0
          },
          "action": {
            "$ref": "#/components/schemas/ShippingRuleAction"
          },
          "evaluated_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "rule_id",
          "name",
          "version",
          "action",
          "evaluated_at"
        ]
      },
      "ShippingRuleAction": {
        "type": "object",
        "properties": {
          "service_code": {
            "type": [
              "string",
              "null"
            ],
            "default": null
          },
          "strategy": {
            "type": "string",
            "enum": [
              "service",
              "cheapest",
              "fastest",
              "best_value"
            ],
            "default": "cheapest"
          },
          "preset_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "default": null,
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "insurance": {
            "type": "boolean",
            "default": false
          },
          "signature": {
            "type": "string",
            "enum": [
              "none",
              "standard",
              "adult"
            ],
            "default": "none"
          }
        }
      },
      "Order": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "order"
            ]
          },
          "store_connection_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "platform": {
            "$ref": "#/components/schemas/StorePlatform"
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "number": {
            "type": "string",
            "example": "#1042"
          },
          "status": {
            "type": "string",
            "enum": [
              "awaiting",
              "shipped",
              "on_hold",
              "cancelled"
            ]
          },
          "customer_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "customer_email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email"
          },
          "ship_to": {
            "$ref": "#/components/schemas/AddressSnapshot"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderItem"
            }
          },
          "total": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              },
              {
                "type": [
                  "object",
                  "null"
                ]
              }
            ]
          },
          "shipping_paid": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              },
              {
                "type": [
                  "object",
                  "null"
                ]
              }
            ]
          },
          "weight": {
            "$ref": "#/components/schemas/Weight"
          },
          "requested_service": {
            "type": [
              "string",
              "null"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "shipping_rule": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "rule_id": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uuid",
                "description": "Null when no rule matched and the default applies",
                "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "version": {
                "type": [
                  "integer",
                  "null"
                ],
                "exclusiveMinimum": 0
              },
              "action": {
                "$ref": "#/components/schemas/ShippingRuleAction"
              },
              "evaluated_at": {
                "type": "string",
                "format": "date-time",
                "description": "RFC 3339 timestamp",
                "example": "2026-10-28T12:00:00Z"
              }
            },
            "required": [
              "rule_id",
              "name",
              "version",
              "action",
              "evaluated_at"
            ],
            "description": "Rule decision for this order (null until rules are evaluated)"
          },
          "shipment_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "placed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "store_connection_id",
          "platform",
          "external_id",
          "number",
          "status",
          "customer_name",
          "customer_email",
          "ship_to",
          "items",
          "total",
          "shipping_paid",
          "weight",
          "requested_service",
          "tags",
          "shipping_rule",
          "shipment_id",
          "placed_at",
          "created_at",
          "updated_at"
        ]
      },
      "StorePlatform": {
        "type": "string",
        "enum": [
          "shopify",
          "etsy",
          "ebay",
          "woocommerce",
          "amazon",
          "squarespace",
          "wix",
          "bigcommerce",
          "tiktok_shop",
          "csv",
          "manual"
        ]
      },
      "OrderItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "sku": {
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "type": "string"
          },
          "quantity": {
            "type": "integer",
            "exclusiveMinimum": 0
          },
          "unit_price": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              },
              {
                "type": [
                  "object",
                  "null"
                ]
              }
            ]
          },
          "weight": {
            "$ref": "#/components/schemas/Weight"
          },
          "hs_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "origin_country": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[A-Z]{2}$",
            "description": "ISO 3166-1 alpha-2",
            "example": "US"
          }
        },
        "required": [
          "id",
          "sku",
          "title",
          "quantity",
          "unit_price",
          "weight",
          "hs_code",
          "origin_country"
        ]
      },
      "OrderCounts": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "order_counts"
            ]
          },
          "awaiting": {
            "type": "integer",
            "minimum": 0
          },
          "shipped": {
            "type": "integer",
            "minimum": 0
          },
          "on_hold": {
            "type": "integer",
            "minimum": 0
          },
          "cancelled": {
            "type": "integer",
            "minimum": 0
          }
        },
        "required": [
          "object",
          "awaiting",
          "shipped",
          "on_hold",
          "cancelled"
        ]
      },
      "OrderCreate": {
        "type": "object",
        "properties": {
          "number": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60,
            "description": "Your order number. Generated (M-…) when omitted."
          },
          "customer_name": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 200,
            "default": null
          },
          "customer_email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email",
            "default": null
          },
          "ship_to": {
            "$ref": "#/components/schemas/AddressSnapshot"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderItemCreate"
            },
            "minItems": 1,
            "maxItems": 500
          },
          "total": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              },
              {
                "type": [
                  "object",
                  "null"
                ]
              }
            ]
          },
          "shipping_paid": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              },
              {
                "type": [
                  "object",
                  "null"
                ]
              }
            ]
          },
          "weight": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "value": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 100000
              },
              "unit": {
                "type": "string",
                "enum": [
                  "oz",
                  "lb",
                  "g",
                  "kg"
                ]
              }
            },
            "default": null,
            "required": [
              "value",
              "unit"
            ],
            "description": "Total weight. Defaults to the sum of item weights."
          },
          "requested_service": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 200,
            "default": null
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 60
            },
            "maxItems": 50,
            "default": []
          },
          "placed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "default": null,
            "description": "Defaults to now",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "ship_to",
          "items"
        ]
      },
      "OrderItemCreate": {
        "type": "object",
        "properties": {
          "sku": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "default": null
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "quantity": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 100000
          },
          "unit_price": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              },
              {
                "type": [
                  "object",
                  "null"
                ]
              }
            ]
          },
          "weight": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "value": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 100000
              },
              "unit": {
                "type": "string",
                "enum": [
                  "oz",
                  "lb",
                  "g",
                  "kg"
                ]
              }
            },
            "default": null,
            "required": [
              "value",
              "unit"
            ],
            "description": "Weight per unit"
          },
          "hs_code": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{6,10}$",
            "default": null
          },
          "origin_country": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[A-Z]{2}$",
            "default": null,
            "description": "ISO 3166-1 alpha-2",
            "example": "US"
          }
        },
        "required": [
          "title",
          "quantity"
        ]
      },
      "OrderImport": {
        "type": "object",
        "properties": {
          "csv": {
            "type": "string",
            "minLength": 1,
            "maxLength": 5000000,
            "description": "CSV text with a header row. Columns (case-insensitive; common aliases accepted): order_number*, name, email, company, address1*, address2, city*, state, postal_code, country*, phone, sku, item*, quantity, unit_price, currency, weight, weight_unit (oz|lb|g|kg), tags (comma-separated), requested_service, placed_at. Rows sharing an order_number become line items of one order. Re-importing an order number already imported is skipped."
          },
          "dry_run": {
            "type": "boolean",
            "default": false,
            "description": "Validate and report without saving"
          }
        },
        "required": [
          "csv"
        ]
      },
      "OrderImportError": {
        "type": "object",
        "properties": {
          "row": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "description": "1-based data row (the header is row 0)"
          },
          "order_number": {
            "type": [
              "string",
              "null"
            ]
          },
          "column": {
            "type": [
              "string",
              "null"
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "row",
          "order_number",
          "column",
          "message"
        ]
      },
      "OrderImportResult": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "order_import"
            ]
          },
          "dry_run": {
            "type": "boolean"
          },
          "rows": {
            "type": "integer",
            "minimum": 0
          },
          "orders_found": {
            "type": "integer",
            "minimum": 0
          },
          "created": {
            "type": "integer",
            "minimum": 0
          },
          "duplicates": {
            "type": "integer",
            "minimum": 0,
            "description": "Already imported; left unchanged"
          },
          "failed": {
            "type": "integer",
            "minimum": 0
          },
          "order_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "description": "Ids of created orders (empty on dry runs)"
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderImportError"
            },
            "maxItems": 1000
          }
        },
        "required": [
          "object",
          "dry_run",
          "rows",
          "orders_found",
          "created",
          "duplicates",
          "failed",
          "order_ids",
          "errors"
        ]
      },
      "OrderList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Order"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
        ]
      },
      "OrderStatus": {
        "type": "string",
        "enum": [
          "awaiting",
          "shipped",
          "on_hold",
          "cancelled"
        ]
      },
      "OrderUpdate": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "awaiting",
              "on_hold",
              "cancelled"
            ],
            "description": "Orders become `shipped` when a label is bought"
          },
          "customer_name": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 200
          },
          "customer_email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email"
          },
          "ship_to": {
            "$ref": "#/components/schemas/AddressSnapshot"
          },
          "weight": {
            "$ref": "#/components/schemas/Weight"
          },
          "requested_service": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 200
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 60
            },
            "maxItems": 50
          }
        }
      },
      "ShippingRule": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "shipping_rule"
            ]
          },
          "name": {
            "type": "string"
          },
          "position": {
            "type": "integer",
            "minimum": 0,
            "description": "Evaluation order; first match wins"
          },
          "enabled": {
            "type": "boolean"
          },
          "conditions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShippingRuleCondition"
            },
            "description": "All must match (AND). Empty = matches every order."
          },
          "action": {
            "$ref": "#/components/schemas/ShippingRuleAction"
          },
          "version": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "description": "Bumped when the rule definition is edited; orders record the version that matched"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "name",
          "position",
          "enabled",
          "conditions",
          "action",
          "version",
          "created_at",
          "updated_at"
        ]
      },
      "ShippingRuleCondition": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "enum": [
              "weight",
              "store",
              "order_total",
              "destination_country",
              "sku",
              "tag",
              "item_count"
            ]
          },
          "op": {
            "type": "string",
            "enum": [
              "eq",
              "neq",
              "lt",
              "lte",
              "gt",
              "gte",
              "in",
              "not_in",
              "contains"
            ]
          },
          "value": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ]
          }
        },
        "required": [
          "field",
          "op",
          "value"
        ],
        "description": "One test on an order. `weight`: number in the store's weight unit or a string with a unit (\"1.5 lb\"); lt/lte/gt/gte/eq/neq. `order_total`: minor units in the order's currency; numeric ops. `item_count`: total quantity; numeric ops. `destination_country`: ISO code, or \"domestic\" / \"international\"; eq/neq/in/not_in. `store`: a store connection id or a platform (\"shopify\", \"csv\"…); eq/neq/in/not_in. `sku` / `tag`: case-insensitive; eq/in/contains match any item SKU or tag, neq/not_in require no match."
      },
      "ShippingRuleApplication": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "shipping_rule_application"
            ]
          },
          "evaluated": {
            "type": "integer",
            "minimum": 0
          },
          "matched": {
            "type": "integer",
            "minimum": 0,
            "description": "Orders a rule matched; the rest use the default (cheapest rate)"
          }
        },
        "required": [
          "object",
          "evaluated",
          "matched"
        ]
      },
      "ShippingRuleApply": {
        "type": "object",
        "properties": {
          "order_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "minItems": 1,
            "maxItems": 1000,
            "description": "Defaults to every order awaiting shipment"
          }
        }
      },
      "ShippingRuleCreate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "position": {
            "type": "integer",
            "minimum": 0
          },
          "enabled": {
            "type": "boolean",
            "default": true
          },
          "conditions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShippingRuleCondition"
            },
            "maxItems": 20
          },
          "action": {
            "$ref": "#/components/schemas/ShippingRuleAction"
          }
        },
        "required": [
          "name",
          "conditions",
          "action"
        ]
      },
      "ShippingRuleList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShippingRule"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
        ]
      },
      "ShippingRuleReorder": {
        "type": "object",
        "properties": {
          "ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "minItems": 1,
            "maxItems": 200,
            "description": "Every rule id, in the new evaluation order"
          }
        },
        "required": [
          "ids"
        ]
      },
      "ShippingRuleUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "enabled": {
            "type": "boolean"
          },
          "conditions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShippingRuleCondition"
            },
            "maxItems": 20
          },
          "action": {
            "$ref": "#/components/schemas/ShippingRuleAction"
          }
        }
      },
      "StoreConnection": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "store_connection"
            ]
          },
          "platform": {
            "$ref": "#/components/schemas/StorePlatform"
          },
          "shop_name": {
            "type": "string"
          },
          "shop_domain": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "paused",
              "error",
              "disconnected"
            ]
          },
          "last_synced_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "last_error": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "platform",
          "shop_name",
          "shop_domain",
          "status",
          "last_synced_at",
          "last_error",
          "created_at"
        ]
      },
      "StoreConnectionAuthorization": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "store_connection_authorization"
            ]
          },
          "platform": {
            "type": "string",
            "enum": [
              "shopify",
              "woocommerce"
            ]
          },
          "authorize_url": {
            "type": "string",
            "format": "uri",
            "description": "Send the merchant here to approve the connection"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "object",
          "platform",
          "authorize_url",
          "expires_at"
        ]
      },
      "StoreConnectionCreate": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "platform": {
                "type": "string",
                "enum": [
                  "shopify"
                ]
              },
              "shop_domain": {
                "type": "string",
                "pattern": "^[a-z0-9][a-z0-9-]*\\.myshopify\\.com$",
                "example": "salty-goods.myshopify.com"
              },
              "return_url": {
                "type": "string",
                "format": "uri",
                "description": "Where to send the merchant after they approve (or cancel), with `?store_connection=<id>` or `?error=<code>`"
              }
            },
            "required": [
              "platform",
              "shop_domain",
              "return_url"
            ]
          },
          {
            "type": "object",
            "properties": {
              "platform": {
                "type": "string",
                "enum": [
                  "woocommerce"
                ]
              },
              "store_url": {
                "type": "string",
                "maxLength": 255,
                "format": "uri",
                "description": "The WordPress site running WooCommerce (https)",
                "example": "https://saltygoods.co"
              },
              "return_url": {
                "type": "string",
                "format": "uri",
                "description": "Where to send the merchant after they approve (or cancel), with `?store_connection=<id>` or `?error=<code>`"
              }
            },
            "required": [
              "platform",
              "store_url",
              "return_url"
            ]
          }
        ]
      },
      "StoreConnectionList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StoreConnection"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
        ]
      },
      "Balance": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "balance"
            ]
          },
          "available": {
            "$ref": "#/components/schemas/Money"
          },
          "reserved": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Minor units (e.g. cents)",
                "example": 412
              },
              "currency": {
                "type": "string",
                "pattern": "^[A-Z]{3}$",
                "description": "ISO 4217",
                "example": "USD"
              }
            },
            "required": [
              "amount",
              "currency"
            ],
            "description": "Held for labels being purchased"
          },
          "auto_reload": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "threshold": {
                "$ref": "#/components/schemas/Money"
              },
              "amount": {
                "$ref": "#/components/schemas/Money"
              }
            },
            "required": [
              "enabled",
              "threshold",
              "amount"
            ]
          }
        },
        "required": [
          "object",
          "available",
          "reserved",
          "auto_reload"
        ]
      },
      "BalanceTransaction": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "balance_transaction"
            ]
          },
          "kind": {
            "type": "string",
            "enum": [
              "top_up",
              "reserve",
              "capture",
              "release",
              "refund",
              "adjust",
              "fee"
            ]
          },
          "amount": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Minor units (e.g. cents)",
                "example": 412
              },
              "currency": {
                "type": "string",
                "pattern": "^[A-Z]{3}$",
                "description": "ISO 4217",
                "example": "USD"
              }
            },
            "required": [
              "amount",
              "currency"
            ],
            "description": "Signed change to the store's balance (available + reserved): top-ups and refunds are positive, label charges, fees and carrier adjustments negative. Holds for labels being purchased show up in `Balance.reserved`, not here."
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "reference": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "type": {
                "type": "string"
              },
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "UUIDv7",
                "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
              }
            },
            "required": [
              "type",
              "id"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "kind",
          "amount",
          "description",
          "reference",
          "created_at"
        ]
      },
      "BalanceTransactionList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BalanceTransaction"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
        ]
      },
      "Payment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "payment"
            ]
          },
          "kind": {
            "type": "string",
            "enum": [
              "top_up",
              "auto_reload",
              "refund"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "succeeded",
              "failed",
              "refunded",
              "disputed"
            ]
          },
          "amount": {
            "$ref": "#/components/schemas/Money"
          },
          "failure_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "client_secret": {
            "type": [
              "string",
              "null"
            ],
            "description": "Present on top-up creation when additional card authentication is needed. Never log or share."
          },
          "receipt_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "kind",
          "status",
          "amount",
          "failure_reason",
          "receipt_url",
          "created_at"
        ]
      },
      "TestFundsCreate": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "integer",
                "exclusiveMinimum": 0,
                "description": "Minor units (e.g. cents), > 0",
                "example": 2500
              },
              "currency": {
                "type": "string",
                "pattern": "^[A-Z]{3}$",
                "description": "ISO 4217",
                "example": "USD"
              }
            },
            "required": [
              "amount",
              "currency"
            ]
          }
        },
        "required": [
          "amount"
        ],
        "description": "Credit test-mode funds to the store's balance (non-production only)."
      },
      "TopUpCreate": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "integer",
                "exclusiveMinimum": 0,
                "description": "Minor units (e.g. cents), > 0",
                "example": 2500
              },
              "currency": {
                "type": "string",
                "pattern": "^[A-Z]{3}$",
                "description": "ISO 4217",
                "example": "USD"
              }
            },
            "required": [
              "amount",
              "currency"
            ]
          },
          "payment_method_id": {
            "type": "string",
            "description": "Saved payment method; defaults to the store's default"
          }
        },
        "required": [
          "amount"
        ]
      },
      "ApiKey": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "api_key"
            ]
          },
          "name": {
            "type": "string"
          },
          "mode": {
            "type": "string",
            "enum": [
              "test",
              "live"
            ]
          },
          "prefix": {
            "type": "string",
            "example": "os_live_3kf9"
          },
          "last_four": {
            "type": "string"
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiKeyScope"
            }
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "revoked_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "name",
          "mode",
          "prefix",
          "last_four",
          "scopes",
          "last_used_at",
          "expires_at",
          "revoked_at",
          "created_at"
        ]
      },
      "ApiKeyScope": {
        "type": "string",
        "enum": [
          "*",
          "read",
          "ship",
          "orders",
          "webhooks",
          "billing"
        ]
      },
      "ApiKeyCreate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60
          },
          "mode": {
            "type": "string",
            "enum": [
              "test",
              "live"
            ]
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiKeyScope"
            },
            "minItems": 1,
            "maxItems": 6,
            "default": [
              "read"
            ]
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "default": null,
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "name",
          "mode"
        ]
      },
      "ApiKeyList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiKey"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
        ]
      },
      "ApiKeyWithSecret": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "api_key"
            ]
          },
          "name": {
            "type": "string"
          },
          "mode": {
            "type": "string",
            "enum": [
              "test",
              "live"
            ]
          },
          "prefix": {
            "type": "string",
            "example": "os_live_3kf9"
          },
          "last_four": {
            "type": "string"
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiKeyScope"
            }
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "revoked_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "secret": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "object",
          "name",
          "mode",
          "prefix",
          "last_four",
          "scopes",
          "last_used_at",
          "expires_at",
          "revoked_at",
          "created_at",
          "secret"
        ]
      },
      "ApiRequestLog": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "api_request_log"
            ]
          },
          "request_id": {
            "type": "string"
          },
          "api_key_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "mode": {
            "type": "string",
            "enum": [
              "test",
              "live"
            ]
          },
          "method": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "status_code": {
            "type": "integer"
          },
          "duration_ms": {
            "type": "integer",
            "minimum": 0
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "request_id",
          "api_key_id",
          "mode",
          "method",
          "path",
          "status_code",
          "duration_ms",
          "created_at"
        ]
      },
      "ApiRequestLogList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiRequestLog"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
        ]
      },
      "AuditLogEntry": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "audit_log_entry"
            ]
          },
          "actor": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "user",
                  "api_key",
                  "system",
                  "staff"
                ]
              },
              "id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "type",
              "id",
              "name"
            ]
          },
          "action": {
            "type": "string",
            "example": "label.voided"
          },
          "target": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "type": {
                "type": "string"
              },
              "id": {
                "type": "string"
              }
            },
            "required": [
              "type",
              "id"
            ]
          },
          "ip": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "actor",
          "action",
          "target",
          "ip",
          "created_at"
        ]
      },
      "DeveloperListQuery": {
        "type": "object",
        "properties": {
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 20
          },
          "cursor": {
            "type": "string",
            "maxLength": 200,
            "description": "Opaque cursor from `next_cursor`"
          },
          "mode": {
            "type": "string",
            "enum": [
              "test",
              "live"
            ]
          }
        }
      },
      "Event": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "event"
            ]
          },
          "type": {
            "$ref": "#/components/schemas/EventType"
          },
          "mode": {
            "type": "string",
            "enum": [
              "test",
              "live"
            ]
          },
          "data": {
            "type": "object",
            "properties": {
              "object": {
                "type": "object",
                "additionalProperties": {}
              }
            },
            "required": [
              "object"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "type",
          "mode",
          "data",
          "created_at"
        ]
      },
      "EventType": {
        "type": "string",
        "enum": [
          "label.created",
          "label.voided",
          "tracker.updated",
          "order.imported",
          "balance.low",
          "batch.completed"
        ]
      },
      "WebhookDelivery": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "webhook_delivery"
            ]
          },
          "endpoint_id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "event_id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "event_type": {
            "$ref": "#/components/schemas/EventType"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "succeeded",
              "failed",
              "retrying"
            ]
          },
          "attempts": {
            "type": "integer"
          },
          "last_response_status": {
            "type": [
              "integer",
              "null"
            ]
          },
          "next_attempt_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "delivered_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "endpoint_id",
          "event_id",
          "event_type",
          "status",
          "attempts",
          "last_response_status",
          "next_attempt_at",
          "delivered_at",
          "created_at"
        ]
      },
      "WebhookDeliveryList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookDelivery"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
        ]
      },
      "WebhookDeliveryListQuery": {
        "type": "object",
        "properties": {
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 20
          },
          "cursor": {
            "type": "string",
            "maxLength": 200,
            "description": "Opaque cursor from `next_cursor`"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "succeeded",
              "failed",
              "retrying"
            ]
          }
        }
      },
      "WebhookEndpoint": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "webhook_endpoint"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "mode": {
            "type": "string",
            "enum": [
              "test",
              "live"
            ]
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventType"
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "enabled",
              "disabled",
              "auto_disabled"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "url",
          "description",
          "mode",
          "events",
          "status",
          "created_at"
        ]
      },
      "WebhookEndpointCreate": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 200,
            "default": null
          },
          "mode": {
            "type": "string",
            "enum": [
              "test",
              "live"
            ]
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventType"
            },
            "minItems": 1
          }
        },
        "required": [
          "url",
          "mode",
          "events"
        ]
      },
      "WebhookEndpointList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookEndpoint"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
        ]
      },
      "WebhookEndpointUpdate": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 200
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventType"
            },
            "minItems": 1
          },
          "status": {
            "type": "string",
            "enum": [
              "enabled",
              "disabled"
            ]
          }
        },
        "additionalProperties": false
      },
      "WebhookEndpointWithSecret": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "webhook_endpoint"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "mode": {
            "type": "string",
            "enum": [
              "test",
              "live"
            ]
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventType"
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "enabled",
              "disabled",
              "auto_disabled"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "signing_secret": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "object",
          "url",
          "description",
          "mode",
          "events",
          "status",
          "created_at",
          "signing_secret"
        ]
      },
      "BatchLookup": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "object": {
                "type": "string",
                "enum": [
                  "batch_lookup"
                ]
              },
              "status": {
                "type": "string",
                "enum": [
                  "found"
                ]
              },
              "batch_id": {
                "type": "string",
                "format": "uuid",
                "description": "UUIDv7",
                "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
              },
              "batch_status": {
                "type": "string",
                "enum": [
                  "pending",
                  "processing",
                  "completed",
                  "partial",
                  "failed"
                ]
              }
            },
            "required": [
              "object",
              "status",
              "batch_id",
              "batch_status"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "object": {
                "type": "string",
                "enum": [
                  "batch_lookup"
                ]
              },
              "status": {
                "type": "string",
                "enum": [
                  "unknown"
                ]
              },
              "batch_id": {
                "type": "null"
              },
              "batch_status": {
                "type": "null"
              }
            },
            "required": [
              "object",
              "status",
              "batch_id",
              "batch_status"
            ],
            "additionalProperties": false
          }
        ],
        "description": "A fresh lookup within the caller's organization and mode. Unknown does not prove failure: the original request may still commit. It never authorizes another purchase key."
      },
      "BatchLookupRequest": {
        "type": "object",
        "properties": {
          "request_key": {
            "type": "string",
            "pattern": "^[\\x21-\\x7e]{1,255}$",
            "description": "The original batch purchase Idempotency-Key, preserved exactly. Never place it in the URL or replace it with a new purchase key."
          }
        },
        "required": [
          "request_key"
        ],
        "additionalProperties": false
      },
      "CardSetup": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "card_setup"
            ]
          },
          "id": {
            "type": "string"
          },
          "client_secret": {
            "type": "string"
          },
          "publishable_key": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "object",
          "id",
          "client_secret",
          "publishable_key"
        ]
      },
      "StoreBillingSettings": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "billing_settings"
            ]
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "description": "ISO 4217",
            "example": "USD"
          },
          "publishable_key": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^pk_(test|live)_",
            "description": "Publishable payment key for the authenticated mode; null for mock or unconfigured billing. Output only."
          },
          "default_payment_method_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "auto_reload": {
            "type": "object",
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "threshold": {
                "$ref": "#/components/schemas/Money"
              },
              "amount": {
                "$ref": "#/components/schemas/Money"
              }
            },
            "required": [
              "enabled",
              "threshold",
              "amount"
            ]
          }
        },
        "required": [
          "object",
          "currency",
          "default_payment_method_id",
          "auto_reload"
        ]
      },
      "PaymentReceipt": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "receipt"
            ]
          },
          "payment_id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "object",
          "payment_id",
          "url",
          "expires_at"
        ]
      },
      "SavedPaymentMethodList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SavedPaymentMethod"
            }
          }
        },
        "required": [
          "object",
          "data"
        ]
      },
      "SavedPaymentMethod": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1
          },
          "object": {
            "type": "string",
            "enum": [
              "payment_method"
            ]
          },
          "brand": {
            "type": "string"
          },
          "last4": {
            "type": "string",
            "pattern": "^\\d{4}$"
          },
          "exp_month": {
            "type": "integer",
            "minimum": 1,
            "maximum": 12
          },
          "exp_year": {
            "type": "integer",
            "minimum": 2000
          },
          "is_default": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "object",
          "brand",
          "last4",
          "exp_month",
          "exp_year",
          "is_default"
        ]
      },
      "PaymentList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Payment"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
        ]
      },
      "StoreBillingUpdate": {
        "type": "object",
        "properties": {
          "default_payment_method_id": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1
          },
          "auto_reload": {
            "type": "object",
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "threshold": {
                "type": "object",
                "properties": {
                  "amount": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "currency": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$",
                    "description": "ISO 4217",
                    "example": "USD"
                  }
                },
                "required": [
                  "amount",
                  "currency"
                ]
              },
              "amount": {
                "type": "object",
                "properties": {
                  "amount": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 1000000
                  },
                  "currency": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$",
                    "description": "ISO 4217",
                    "example": "USD"
                  }
                },
                "required": [
                  "amount",
                  "currency"
                ]
              }
            },
            "required": [
              "enabled",
              "threshold",
              "amount"
            ]
          }
        },
        "additionalProperties": false
      },
      "SpendReportExport": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "report_export"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "content_type": {
            "type": "string",
            "enum": [
              "text/csv"
            ]
          }
        },
        "required": [
          "object",
          "url",
          "expires_at",
          "content_type"
        ]
      },
      "SpendReport": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "spend_report"
            ]
          },
          "from": {
            "type": "string",
            "format": "date"
          },
          "to": {
            "type": "string",
            "format": "date"
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "description": "ISO 4217",
            "example": "USD"
          },
          "totals": {
            "type": "object",
            "properties": {
              "labels": {
                "type": "integer",
                "minimum": 0
              },
              "postage": {
                "$ref": "#/components/schemas/Money"
              },
              "adjustments": {
                "$ref": "#/components/schemas/Money"
              },
              "fees": {
                "$ref": "#/components/schemas/Money"
              },
              "refunds": {
                "$ref": "#/components/schemas/Money"
              },
              "net_spend": {
                "$ref": "#/components/schemas/Money"
              },
              "retail": {
                "$ref": "#/components/schemas/Money"
              },
              "savings": {
                "$ref": "#/components/schemas/Money"
              }
            },
            "required": [
              "labels",
              "postage",
              "adjustments",
              "fees",
              "refunds",
              "net_spend",
              "retail",
              "savings"
            ]
          },
          "groups": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "labels": {
                  "type": "integer",
                  "minimum": 0
                },
                "postage": {
                  "$ref": "#/components/schemas/Money"
                },
                "adjustments": {
                  "$ref": "#/components/schemas/Money"
                },
                "fees": {
                  "$ref": "#/components/schemas/Money"
                },
                "refunds": {
                  "$ref": "#/components/schemas/Money"
                },
                "net_spend": {
                  "$ref": "#/components/schemas/Money"
                },
                "retail": {
                  "$ref": "#/components/schemas/Money"
                },
                "savings": {
                  "$ref": "#/components/schemas/Money"
                },
                "week_start": {
                  "type": "string",
                  "format": "date"
                },
                "courier_id": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "service_code": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "labels",
                "postage",
                "adjustments",
                "fees",
                "refunds",
                "net_spend",
                "retail",
                "savings",
                "week_start",
                "courier_id",
                "service_code"
              ]
            }
          }
        },
        "required": [
          "object",
          "from",
          "to",
          "currency",
          "totals",
          "groups"
        ]
      },
      "LabelDocuments": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "label_documents"
            ]
          },
          "label_id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "documents": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "customs"
                  ],
                  "description": "Carrier-issued customs forms, including a commercial invoice when supplied, combined in one PDF."
                },
                "format": {
                  "type": "string",
                  "enum": [
                    "pdf"
                  ]
                },
                "url": {
                  "type": "string",
                  "format": "uri",
                  "description": "Short-lived signed download URL."
                },
                "expires_at": {
                  "type": "string",
                  "format": "date-time",
                  "description": "RFC 3339 timestamp",
                  "example": "2026-10-28T12:00:00Z"
                }
              },
              "required": [
                "kind",
                "format",
                "url",
                "expires_at"
              ]
            },
            "maxItems": 1
          }
        },
        "required": [
          "object",
          "label_id",
          "documents"
        ]
      },
      "Batch": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "object": {
            "type": "string",
            "enum": [
              "batch"
            ]
          },
          "mode": {
            "$ref": "#/components/schemas/Mode"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "processing",
              "completed",
              "partial",
              "failed"
            ]
          },
          "format": {
            "type": "string",
            "enum": [
              "pdf"
            ]
          },
          "size": {
            "type": "string",
            "enum": [
              "4x6",
              "letter",
              "a4"
            ]
          },
          "total_count": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000
          },
          "pending_count": {
            "type": "integer",
            "minimum": 0
          },
          "purchased_count": {
            "type": "integer",
            "minimum": 0
          },
          "failed_count": {
            "type": "integer",
            "minimum": 0
          },
          "document_status": {
            "type": "string",
            "enum": [
              "pending",
              "ready",
              "unavailable",
              "not_required"
            ]
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Short-lived link to the combined PDF of successful labels; null while unavailable or in event payloads."
          },
          "url_expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          },
          "completed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC 3339 timestamp",
            "example": "2026-10-28T12:00:00Z"
          }
        },
        "required": [
          "id",
          "object",
          "mode",
          "name",
          "status",
          "format",
          "size",
          "total_count",
          "pending_count",
          "purchased_count",
          "failed_count",
          "document_status",
          "url",
          "url_expires_at",
          "created_at",
          "updated_at",
          "completed_at"
        ]
      },
      "BatchCreate": {
        "type": "object",
        "properties": {
          "rate_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "minItems": 1,
            "maxItems": 1000
          },
          "format": {
            "type": "string",
            "enum": [
              "pdf"
            ],
            "default": "pdf"
          },
          "size": {
            "type": "string",
            "enum": [
              "4x6",
              "letter",
              "a4"
            ],
            "default": "4x6"
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 120,
            "default": null
          }
        },
        "required": [
          "rate_ids"
        ],
        "additionalProperties": false
      },
      "BatchItems": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BatchItem"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
        ]
      },
      "BatchItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "rate_id": {
            "type": "string",
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "label_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "UUIDv7",
            "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "purchasing",
              "purchased",
              "failed"
            ]
          },
          "error": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "id",
          "rate_id",
          "label_id",
          "status",
          "error"
        ]
      },
      "BatchList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Batch"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
        ]
      },
      "AddressValidationResult": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "address_validation"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "verified",
              "unverified",
              "warning",
              "error"
            ]
          },
          "normalized_address": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 100,
                "default": null
              },
              "company": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 100,
                "default": null
              },
              "line1": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              },
              "line2": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 200,
                "default": null
              },
              "city": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "region": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 100,
                "default": null,
                "description": "State / province / county"
              },
              "postal_code": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 20,
                "default": null
              },
              "country": {
                "type": "string",
                "pattern": "^[A-Z]{2}$",
                "description": "ISO 3166-1 alpha-2",
                "example": "US"
              },
              "phone": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 40,
                "default": null
              },
              "email": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "email",
                "default": null
              },
              "residential": {
                "type": [
                  "boolean",
                  "null"
                ],
                "default": null
              }
            },
            "required": [
              "line1",
              "city",
              "country"
            ],
            "description": "Suggested address only. Apply it explicitly after review; saved addresses and shipments are unchanged."
          },
          "messages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "address_verified",
                    "address_corrected",
                    "address_unverified",
                    "address_not_found",
                    "country_not_supported",
                    "postal_code_invalid",
                    "region_invalid",
                    "city_invalid",
                    "street_invalid",
                    "unit_missing",
                    "unit_invalid",
                    "address_ambiguous",
                    "validation_partial"
                  ]
                },
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "code",
                "message"
              ]
            }
          }
        },
        "required": [
          "object",
          "status",
          "normalized_address",
          "messages"
        ]
      },
      "AddressValidate": {
        "type": "object",
        "properties": {
          "address": {
            "type": "object",
            "properties": {
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 100,
                "default": null
              },
              "company": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 100,
                "default": null
              },
              "line1": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              },
              "line2": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 200,
                "default": null
              },
              "city": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "region": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 100,
                "default": null,
                "description": "State / province / county"
              },
              "postal_code": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 20,
                "default": null
              },
              "country": {
                "type": "string",
                "pattern": "^[A-Z]{2}$",
                "description": "ISO 3166-1 alpha-2",
                "example": "US"
              },
              "phone": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 40,
                "default": null
              },
              "email": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "email",
                "default": null
              },
              "residential": {
                "type": [
                  "boolean",
                  "null"
                ],
                "default": null
              }
            },
            "required": [
              "line1",
              "city",
              "country"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "address"
        ],
        "additionalProperties": false
      }
    },
    "parameters": {}
  },
  "paths": {
    "/v1/batches/lookup": {
      "post": {
        "operationId": "lookupBatch",
        "x-octoship-read-only": true,
        "summary": "Recover an accepted batch by its original request key",
        "description": "Read-only POST with read permission. No lookup Idempotency-Key is required and responses use Cache-Control: no-store. Reads an existing batch without creating work, changing a reservation or reopening the original request claim. An unknown result may still commit; retain the original body/key and never start a replacement purchase automatically.",
        "tags": [
          "batches"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchLookupRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recover an accepted batch by its original request key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchLookup"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/billing/card_setup": {
      "post": {
        "operationId": "createCardSetup",
        "summary": "Start saving a payment card",
        "tags": [
          "billing"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {}
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Start saving a payment card",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardSetup"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/billing/payment_methods/{id}": {
      "delete": {
        "operationId": "deletePaymentMethod",
        "summary": "Remove a saved payment card",
        "tags": [
          "billing"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "required": true,
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "responses": {
          "200": {
            "description": "Remove a saved payment card",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "object": {
                      "type": "string",
                      "enum": [
                        "payment_method"
                      ]
                    },
                    "deleted": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "object",
                    "deleted"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/billing": {
      "get": {
        "operationId": "getBillingSettings",
        "summary": "Retrieve billing settings",
        "tags": [
          "billing"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Retrieve billing settings",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoreBillingSettings"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateBillingSettings",
        "summary": "Update saved card and auto-reload settings",
        "tags": [
          "billing"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StoreBillingUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update saved card and auto-reload settings",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoreBillingSettings"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/{id}/receipt": {
      "get": {
        "operationId": "getPaymentReceipt",
        "summary": "Download a payment receipt",
        "tags": [
          "billing"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Download a payment receipt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentReceipt"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/billing/payment_methods": {
      "get": {
        "operationId": "listPaymentMethods",
        "summary": "List saved payment cards",
        "tags": [
          "billing"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "List saved payment cards",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SavedPaymentMethodList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments": {
      "get": {
        "operationId": "listPayments",
        "summary": "List payments",
        "tags": [
          "billing"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "maxLength": 200,
              "description": "Opaque cursor from `next_cursor`"
            },
            "required": false,
            "description": "Opaque cursor from `next_cursor`",
            "name": "cursor",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List payments",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/reports/spend/exports": {
      "post": {
        "operationId": "exportSpendReport",
        "summary": "Export postage spend as CSV",
        "tags": [
          "reports"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "from": {
                    "type": "string",
                    "format": "date",
                    "description": "First UTC day, inclusive"
                  },
                  "to": {
                    "type": "string",
                    "format": "date",
                    "description": "Last UTC day, exclusive; at most 366 days after from"
                  },
                  "currency": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$",
                    "description": "ISO 4217",
                    "example": "USD"
                  }
                },
                "required": [
                  "from",
                  "to"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Export postage spend as CSV",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpendReportExport"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/reports/spend": {
      "get": {
        "operationId": "getSpendReport",
        "summary": "Report postage spend by carrier, service and week",
        "description": "Ledger-backed totals for the authenticated store and mode. Refunds are reported when settled. All amounts use minor units.",
        "tags": [
          "reports"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "First UTC day, inclusive"
            },
            "required": true,
            "description": "First UTC day, inclusive",
            "name": "from",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Last UTC day, exclusive; at most 366 days after from"
            },
            "required": true,
            "description": "Last UTC day, exclusive; at most 366 days after from",
            "name": "to",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^[A-Z]{3}$",
              "description": "ISO 4217",
              "example": "USD"
            },
            "required": false,
            "description": "ISO 4217",
            "name": "currency",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Report postage spend by carrier, service and week",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpendReport"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhook_endpoints": {
      "get": {
        "operationId": "listWebhookEndpoints",
        "summary": "List webhook endpoints",
        "tags": [
          "webhooks"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "maxLength": 200,
              "description": "Opaque cursor from `next_cursor`"
            },
            "required": false,
            "description": "Opaque cursor from `next_cursor`",
            "name": "cursor",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "test",
                "live"
              ]
            },
            "required": false,
            "name": "mode",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List webhook endpoints",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createWebhookEndpoint",
        "summary": "Create a webhook endpoint",
        "description": "Only HTTPS destinations are accepted. The signing secret is returned on creation; keep it secure. Endpoint mode must match the authenticated mode.",
        "tags": [
          "webhooks"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEndpointCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Create a webhook endpoint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointWithSecret"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhook_endpoints/{id}": {
      "get": {
        "operationId": "getWebhookEndpoint",
        "summary": "Retrieve a webhook endpoint",
        "tags": [
          "webhooks"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Retrieve a webhook endpoint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpoint"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateWebhookEndpoint",
        "summary": "Update a webhook endpoint",
        "tags": [
          "webhooks"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEndpointUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update a webhook endpoint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpoint"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteWebhookEndpoint",
        "summary": "Delete a webhook endpoint",
        "tags": [
          "webhooks"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "responses": {
          "200": {
            "description": "Delete a webhook endpoint",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "UUIDv7",
                      "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
                    },
                    "object": {
                      "type": "string",
                      "enum": [
                        "webhook_endpoint"
                      ]
                    },
                    "deleted": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "object",
                    "deleted"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhook_endpoints/{id}/deliveries": {
      "get": {
        "operationId": "listWebhookDeliveries",
        "summary": "List webhook deliveries",
        "tags": [
          "webhooks"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "maxLength": 200,
              "description": "Opaque cursor from `next_cursor`"
            },
            "required": false,
            "description": "Opaque cursor from `next_cursor`",
            "name": "cursor",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "succeeded",
                "failed",
                "retrying"
              ]
            },
            "required": false,
            "name": "status",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List webhook deliveries",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDeliveryList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhook_endpoints/{id}/deliveries/{delivery_id}/replay": {
      "post": {
        "operationId": "replayWebhookDelivery",
        "summary": "Replay a webhook delivery",
        "description": "Schedules a new delivery attempt using the original event ID and payload. Receivers must deduplicate by event ID.",
        "tags": [
          "webhooks"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "delivery_id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "responses": {
          "202": {
            "description": "Replay a webhook delivery",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDelivery"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/balance": {
      "get": {
        "operationId": "getBalance",
        "summary": "Retrieve the postage balance",
        "description": "Available funds, funds held for labels being purchased, and auto-reload settings, for one currency.",
        "tags": [
          "balance"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "pattern": "^[A-Z]{3}$",
              "description": "Defaults to the store's currency",
              "example": "USD"
            },
            "required": false,
            "description": "Defaults to the store's currency",
            "name": "currency",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Retrieve the postage balance",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Balance"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/balance/transactions": {
      "get": {
        "operationId": "listBalanceTransactions",
        "summary": "List balance transactions",
        "description": "Every change to the balance, newest first: top-ups, label charges, refunds, fees and adjustments.",
        "tags": [
          "balance"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "maxLength": 200,
              "description": "Opaque cursor from `next_cursor`"
            },
            "required": false,
            "description": "Opaque cursor from `next_cursor`",
            "name": "cursor",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^[A-Z]{3}$",
              "description": "Defaults to the store's currency",
              "example": "USD"
            },
            "required": false,
            "description": "Defaults to the store's currency",
            "name": "currency",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List balance transactions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BalanceTransactionList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/balance/top_ups": {
      "post": {
        "operationId": "createTopUp",
        "summary": "Top up the balance",
        "description": "Charges the saved payment method. The balance is credited once the payment succeeds.",
        "tags": [
          "balance"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TopUpCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Top up the balance",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Payment"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/labels": {
      "post": {
        "operationId": "createLabel",
        "summary": "Buy a label",
        "description": "Buys the label for a rate and charges your balance. Usually completes inline (`201`, status `purchased`, `url` set). If the courier is slow you get `202` with status `purchasing`: poll the label until it settles.",
        "tags": [
          "labels"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LabelCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Buy a label",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Label"
                }
              }
            }
          },
          "202": {
            "description": "Buy a label",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Label"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listLabels",
        "summary": "List labels",
        "description": "Newest first.",
        "tags": [
          "labels"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "maxLength": 200,
              "description": "Opaque cursor from `next_cursor`"
            },
            "required": false,
            "description": "Opaque cursor from `next_cursor`",
            "name": "cursor",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": false,
            "description": "UUIDv7",
            "name": "shipment_id",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "purchasing",
                "purchased",
                "void_requested",
                "voided",
                "refunded",
                "failed"
              ]
            },
            "required": false,
            "name": "status",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List labels",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LabelList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/labels/{id}": {
      "get": {
        "operationId": "getLabel",
        "summary": "Retrieve a label",
        "description": "`url` is a short-lived signed link, issued fresh on every read.",
        "tags": [
          "labels"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Retrieve a label",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Label"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/shipments/{id}": {
      "get": {
        "operationId": "getShipment",
        "summary": "Retrieve a shipment",
        "tags": [
          "shipments"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Retrieve a shipment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Shipment"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/trackers/{id}": {
      "get": {
        "operationId": "getTracker",
        "summary": "Retrieve a tracker",
        "description": "Includes the full event timeline, oldest first.",
        "tags": [
          "tracking"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Retrieve a tracker",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tracker"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/shipments": {
      "get": {
        "operationId": "listShipments",
        "summary": "List shipments",
        "description": "Newest first.",
        "tags": [
          "shipments"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "maxLength": 200,
              "description": "Opaque cursor from `next_cursor`"
            },
            "required": false,
            "description": "Opaque cursor from `next_cursor`",
            "name": "cursor",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "rated",
                "purchasing",
                "purchased",
                "voided",
                "failed"
              ]
            },
            "required": false,
            "name": "status",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List shipments",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShipmentList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/trackers": {
      "get": {
        "operationId": "listTrackers",
        "summary": "List trackers",
        "description": "Most recently updated first. `events` is empty in list responses; retrieve a tracker for its timeline.",
        "tags": [
          "tracking"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "maxLength": 200,
              "description": "Opaque cursor from `next_cursor`"
            },
            "required": false,
            "description": "Opaque cursor from `next_cursor`",
            "name": "cursor",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "unknown",
                "label_created",
                "in_transit",
                "out_for_delivery",
                "delivered",
                "exception",
                "returned"
              ]
            },
            "required": false,
            "name": "status",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "required": false,
            "name": "tracking_number",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List trackers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrackerList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/rates": {
      "post": {
        "operationId": "quoteRates",
        "summary": "Rate a shipment",
        "description": "Saves the shipment (status `rated`) and returns live rates from every courier available at its origin, cheapest first, in your store's currency. Couriers that fail to quote are listed in `messages`; the rest are still returned.",
        "tags": [
          "rates"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ShipmentCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rate a shipment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateQuote"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/shipments/{id}/rates": {
      "post": {
        "operationId": "requoteShipment",
        "summary": "Re-rate a shipment",
        "description": "Fresh rates for an existing shipment (e.g. after its rates expired).",
        "tags": [
          "rates"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "responses": {
          "200": {
            "description": "Re-rate a shipment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateQuote"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/labels/{id}/void": {
      "post": {
        "operationId": "voidLabel",
        "summary": "Void an unused label",
        "description": "Cancels an unused label. Status becomes `voided` once the courier confirms (often immediately), or `void_requested` while it's pending; the label price is refunded to your balance on confirmation.",
        "tags": [
          "labels"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "responses": {
          "200": {
            "description": "Void an unused label",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Label"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/labels/{id}/documents": {
      "get": {
        "operationId": "getLabelDocuments",
        "summary": "Retrieve customs documents for a label",
        "description": "Returns fresh signed links to carrier-issued customs PDFs. An empty list means no separate forms were supplied; forms may be electronic or included on the label. Does not buy another label or create a declaration.",
        "tags": [
          "labels"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Retrieve customs documents for a label",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LabelDocuments"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Retrieve customs documents for a label",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Retrieve customs documents for a label",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/batches": {
      "post": {
        "operationId": "createBatch",
        "summary": "Buy a batch of labels",
        "description": "Queues up to 1,000 distinct shipment rates in your current mode. Each label is metered separately. Poll the batch and its items for progress and partial failures. Uncertain purchases remain pending with their holds intact; retries never authorize a new charge.",
        "tags": [
          "batches"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchCreate"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Buy a batch of labels",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Batch"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listBatches",
        "summary": "List label batches",
        "tags": [
          "batches"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "maxLength": 200,
              "description": "Opaque cursor from `next_cursor`"
            },
            "required": false,
            "description": "Opaque cursor from `next_cursor`",
            "name": "cursor",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "processing",
                "completed",
                "partial",
                "failed"
              ]
            },
            "required": false,
            "name": "status",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List label batches",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/batches/{id}": {
      "get": {
        "operationId": "getBatch",
        "summary": "Retrieve batch progress",
        "description": "Includes counts and a fresh combined-PDF link when ready. Completion requires every purchase to reach an authoritative final outcome.",
        "tags": [
          "batches"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Retrieve batch progress",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Batch"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/batches/{id}/items": {
      "get": {
        "operationId": "listBatchItems",
        "summary": "List batch results",
        "description": "Returns each selected rate, its label when allocated, and a customer-safe failure when applicable.",
        "tags": [
          "batches"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "maxLength": 200,
              "description": "Opaque cursor from `next_cursor`"
            },
            "required": false,
            "description": "Opaque cursor from `next_cursor`",
            "name": "cursor",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List batch results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchItems"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/addresses": {
      "get": {
        "operationId": "listAddresses",
        "summary": "List saved addresses",
        "description": "The default ship-from address first, then newest first.",
        "tags": [
          "addresses"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "maxLength": 200,
              "description": "Opaque cursor from `next_cursor`"
            },
            "required": false,
            "description": "Opaque cursor from `next_cursor`",
            "name": "cursor",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "description": "Only the default ship-from address (true) or only the others (false)"
            },
            "required": false,
            "description": "Only the default ship-from address (true) or only the others (false)",
            "name": "default_from",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List saved addresses",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AddressList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createAddress",
        "summary": "Save an address",
        "description": "With `is_default_from: true` it becomes the store's default ship-from address, replacing the previous one.",
        "tags": [
          "addresses"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddressCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Save an address",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Address"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/addresses/{id}": {
      "get": {
        "operationId": "getAddress",
        "summary": "Retrieve a saved address",
        "tags": [
          "addresses"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Retrieve a saved address",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Address"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateAddress",
        "summary": "Update a saved address",
        "description": "Shipments keep the address as it was when they were created.",
        "tags": [
          "addresses"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddressUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update a saved address",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Address"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteAddress",
        "summary": "Delete a saved address",
        "tags": [
          "addresses"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "responses": {
          "200": {
            "description": "Delete a saved address",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "UUIDv7",
                      "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
                    },
                    "object": {
                      "type": "string",
                      "enum": [
                        "address"
                      ]
                    },
                    "deleted": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "object",
                    "deleted"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/addresses/validate": {
      "post": {
        "operationId": "validateAddress",
        "summary": "Validate an address",
        "description": "Checks one address and returns suggested corrections for review. Does not save or change an address or shipment. Availability depends on the store's shipping origin and mode.",
        "tags": [
          "addresses"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddressValidate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validate an address",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AddressValidationResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Validate an address",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/orders": {
      "get": {
        "operationId": "listOrders",
        "summary": "List orders",
        "description": "Newest first (by placed date). Filter by status, platform, store connection, destination or a search term.",
        "tags": [
          "orders"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "maxLength": 200,
              "description": "Opaque cursor from `next_cursor`"
            },
            "required": false,
            "description": "Opaque cursor from `next_cursor`",
            "name": "cursor",
            "in": "query"
          },
          {
            "schema": {
              "$ref": "#/components/schemas/OrderStatus"
            },
            "required": false,
            "name": "status",
            "in": "query"
          },
          {
            "schema": {
              "$ref": "#/components/schemas/StorePlatform"
            },
            "required": false,
            "name": "platform",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": false,
            "description": "UUIDv7",
            "name": "store_connection_id",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^[A-Z]{2}$",
              "description": "ISO 3166-1 alpha-2",
              "example": "US"
            },
            "required": false,
            "description": "ISO 3166-1 alpha-2",
            "name": "destination_country",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "description": "Matches order number, customer, city, SKU or item title"
            },
            "required": false,
            "description": "Matches order number, customer, city, SKU or item title",
            "name": "q",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List orders",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createOrder",
        "summary": "Create a manual order",
        "tags": [
          "orders"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Create a manual order",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/orders/counts": {
      "get": {
        "operationId": "getOrderCounts",
        "summary": "Order counts by status",
        "tags": [
          "orders"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "$ref": "#/components/schemas/StorePlatform"
            },
            "required": false,
            "name": "platform",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": false,
            "description": "UUIDv7",
            "name": "store_connection_id",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Order counts by status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderCounts"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/orders/{id}": {
      "get": {
        "operationId": "getOrder",
        "summary": "Get an order",
        "tags": [
          "orders"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Get an order",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateOrder",
        "summary": "Update an order",
        "description": "Hold, release or cancel an order, or fix its address, weight or tags. Shipped orders can't be changed.",
        "tags": [
          "orders"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update an order",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/orders/import": {
      "post": {
        "operationId": "importOrders",
        "summary": "Import orders from CSV",
        "description": "Valid orders are saved; invalid ones are reported per row and skipped. Idempotent per order number.",
        "tags": [
          "orders"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderImport"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Import orders from CSV",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderImportResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/store_connections": {
      "get": {
        "operationId": "listStoreConnections",
        "summary": "List connected stores",
        "description": "Stores and marketplaces orders are imported from. Use `getOrderCounts?store_connection_id=` for per-store order counts.",
        "tags": [
          "store connections"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "maxLength": 200,
              "description": "Opaque cursor from `next_cursor`"
            },
            "required": false,
            "description": "Opaque cursor from `next_cursor`",
            "name": "cursor",
            "in": "query"
          },
          {
            "schema": {
              "$ref": "#/components/schemas/StorePlatform"
            },
            "required": false,
            "name": "platform",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": false,
              "description": "Disconnected stores are hidden unless true"
            },
            "required": false,
            "description": "Disconnected stores are hidden unless true",
            "name": "include_disconnected",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List connected stores",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoreConnectionList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "connectStore",
        "summary": "Start connecting a store",
        "description": "Returns the platform's approval URL. After the merchant approves, they're sent to `return_url` with `?store_connection=<id>` and recent orders start importing; if they cancel, with `?error=access_denied`. The URL expires after 10 minutes.",
        "tags": [
          "store connections"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StoreConnectionCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Start connecting a store",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoreConnectionAuthorization"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/store_connections/{id}": {
      "get": {
        "operationId": "getStoreConnection",
        "summary": "Retrieve a store connection",
        "tags": [
          "store connections"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Retrieve a store connection",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoreConnection"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteStoreConnection",
        "summary": "Disconnect a store",
        "description": "Stops importing orders and revokes our access to the store. Orders already imported stay.",
        "tags": [
          "store connections"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "responses": {
          "200": {
            "description": "Disconnect a store",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "UUIDv7",
                      "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
                    },
                    "object": {
                      "type": "string",
                      "enum": [
                        "store_connection"
                      ]
                    },
                    "deleted": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "object",
                    "deleted"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/store_connections/{id}/sync": {
      "post": {
        "operationId": "syncStoreConnection",
        "summary": "Sync orders now",
        "description": "Queues an import of orders changed since the last sync. Orders also arrive in real time through platform webhooks.",
        "tags": [
          "store connections"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "responses": {
          "202": {
            "description": "Sync orders now",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoreConnection"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/package_presets": {
      "get": {
        "operationId": "listPackagePresets",
        "summary": "List package presets",
        "description": "The default preset first, then by name.",
        "tags": [
          "package presets"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "maxLength": 200,
              "description": "Opaque cursor from `next_cursor`"
            },
            "required": false,
            "description": "Opaque cursor from `next_cursor`",
            "name": "cursor",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "List package presets",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PackagePresetList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createPackagePreset",
        "summary": "Create a package preset",
        "description": "With `is_default: true` it replaces the store's current default preset.",
        "tags": [
          "package presets"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PackagePresetCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Create a package preset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PackagePreset"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/package_presets/{id}": {
      "get": {
        "operationId": "getPackagePreset",
        "summary": "Retrieve a package preset",
        "tags": [
          "package presets"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Retrieve a package preset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PackagePreset"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updatePackagePreset",
        "summary": "Update a package preset",
        "tags": [
          "package presets"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PackagePresetUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update a package preset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PackagePreset"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deletePackagePreset",
        "summary": "Delete a package preset",
        "description": "Shipments already created with it keep their dimensions. Rules that pointed at it fall back to the order's own package.",
        "tags": [
          "package presets"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "responses": {
          "200": {
            "description": "Delete a package preset",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "UUIDv7",
                      "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
                    },
                    "object": {
                      "type": "string",
                      "enum": [
                        "package_preset"
                      ]
                    },
                    "deleted": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "object",
                    "deleted"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/shipping_rules": {
      "get": {
        "operationId": "listShippingRules",
        "summary": "List shipping rules",
        "description": "Every rule in evaluation order (first match wins; no match → cheapest rate). Not paginated (at most 200 rules).",
        "tags": [
          "shipping rules"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "List shipping rules",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShippingRuleList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createShippingRule",
        "summary": "Create a shipping rule",
        "description": "Added at `position` (default: last); later rules shift down.",
        "tags": [
          "shipping rules"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ShippingRuleCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Create a shipping rule",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShippingRule"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/shipping_rules/{id}": {
      "get": {
        "operationId": "getShippingRule",
        "summary": "Retrieve a shipping rule",
        "tags": [
          "shipping rules"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Retrieve a shipping rule",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShippingRule"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateShippingRule",
        "summary": "Update a shipping rule",
        "tags": [
          "shipping rules"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ShippingRuleUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update a shipping rule",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShippingRule"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteShippingRule",
        "summary": "Delete a shipping rule",
        "tags": [
          "shipping rules"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "UUIDv7",
              "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
            },
            "required": true,
            "description": "UUIDv7",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "responses": {
          "200": {
            "description": "Delete a shipping rule",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "UUIDv7",
                      "example": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
                    },
                    "object": {
                      "type": "string",
                      "enum": [
                        "shipping_rule"
                      ]
                    },
                    "deleted": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "object",
                    "deleted"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/shipping_rules/reorder": {
      "post": {
        "operationId": "reorderShippingRules",
        "summary": "Reorder shipping rules",
        "description": "Send every rule id in the new order.",
        "tags": [
          "shipping rules"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ShippingRuleReorder"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reorder shipping rules",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShippingRuleList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/shipping_rules/apply": {
      "post": {
        "operationId": "applyShippingRules",
        "summary": "Apply rules to orders",
        "description": "Re-evaluates rules for orders awaiting shipment (or the ones given) and records each decision on the order. Orders are also evaluated automatically when imported or edited.",
        "tags": [
          "shipping rules"
        ],
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "required": true,
            "name": "idempotency-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ShippingRuleApply"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Apply rules to orders",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShippingRuleApplication"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict / idempotency key reuse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — see Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {}
}
