{"openapi":"3.1.0","info":{"title":"Octoship API","version":"64fe1963eb055b3bf9b750e9602484285b0529b8","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":{}}