{"info":{"title":"Bookogsend Customer API","version":"1"},"servers":[{"url":"/api/v1/customer"}],"components":{"securitySchemes":{"customerKey":{"type":"http","scheme":"bearer","description":"Required header: `Authorization: Bearer `. Use a Customer API key with the operation's required permission. Never use a dashboard or webshop token."}},"schemas":{"Address":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40,"description":"Person or company name. Required and nonempty after trimming; see maxLength. Shipment services may impose a lower name limit."},"street1":{"type":"string","minLength":1,"maxLength":54,"description":"Primary street address, including house number. Required and nonempty after trimming; see maxLength and service fieldLimits."},"street2":{"default":null,"anyOf":[{"type":"string","maxLength":54},{"type":"null"}],"description":"Optional additional address line. Omit or send null to clear it; see maxLength and service fieldLimits."},"city":{"type":"string","minLength":1,"maxLength":30,"description":"Town or city. Required and nonempty after trimming; see maxLength."},"zip":{"type":"string","minLength":1,"maxLength":10,"description":"Postal code as text, preserving leading zeros. It must match the country for carrier shipments; see maxLength."},"country":{"type":"string","pattern":"^[A-Z]{2}$","description":"Supported country code in two-letter uppercase ISO format, such as DK. The country and service must have an available route and price."},"addressType":{"enum":["RESIDENTIAL","COMMERCIAL"],"type":"string","description":"RESIDENTIAL for a private address or COMMERCIAL for a business address."},"region":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional state, province, or region as text. Omit or send null to clear it."},"attention":{"default":null,"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"description":"Optional contact person or attention line. Omit or send null to clear it; see maxLength."},"email":{"default":null,"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"description":"Valid contact email address, or null. Required for a shipment receiver when GET /services reports receiverEmailRequired."},"phone":{"default":null,"anyOf":[{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$"},{"type":"null"}],"description":"Telephone number in international E.164 format, such as +4512345678, or null. Required for a shipment receiver when receiverPhoneRequired is true."},"mobile":{"default":null,"anyOf":[{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$"},{"type":"null"}],"description":"Mobile number in international E.164 format, such as +4512345678, or null. Required for a shipment receiver when receiverMobileRequired is true."}},"required":["name","street1","city","zip","country","addressType"],"additionalProperties":false},"PickupLocationSearch":{"type":"object","properties":{"street1":{"type":"string","minLength":1,"maxLength":54},"street2":{"default":null,"anyOf":[{"type":"string","maxLength":54},{"type":"null"}]},"city":{"type":"string","minLength":1,"maxLength":30},"region":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}]},"zip":{"type":"string","minLength":1,"maxLength":10},"country":{"type":"string","pattern":"^[A-Z]{2}$"}},"required":["street1","city","zip","country"],"additionalProperties":false},"PickupLocation":{"type":"object","properties":{"provider":{"const":"GLS","description":"Parcel-shop provider."},"externalLocationId":{"type":"string","minLength":1,"description":"GLS parcel-shop ID, used as pickupLocation.externalLocationId."},"name":{"type":"string","minLength":1,"description":"Parcel-shop name."},"street1":{"type":"string","minLength":1,"description":"Parcel-shop primary street address."},"street2":{"type":"string","description":"Second address line, or an empty string."},"zip":{"type":"string","minLength":1,"description":"Parcel-shop postal code as text."},"city":{"type":"string","minLength":1,"description":"Parcel-shop town or city."},"country":{"type":"string","pattern":"^[A-Z]{2}$","description":"Parcel-shop country, matching the requested country."},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Parcel-shop latitude."},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Parcel-shop longitude."},"distanceKm":{"type":"number","minimum":0,"description":"Straight-line distance from the receiver address in kilometres, not driving distance. Results are ordered nearest first."},"openingHours":{"type":"array","items":{"type":"object","properties":{"weekdayISO8601":{"type":"integer","minimum":1,"maximum":7,"description":"ISO weekday: 1 is Monday and 7 is Sunday."},"timeWindows":{"type":"array","items":{"type":"object","properties":{"fromISO8601":{"type":"string","description":"Opening time, such as 09:00."},"toISO8601":{"type":"string","description":"Closing time, such as 18:00."}},"required":["fromISO8601","toISO8601"]},"description":"Opening intervals for this weekday. May be empty."}},"required":["weekdayISO8601","timeWindows"]},"description":"Structured opening hours for display. Shipment requests need only the shop ID."}},"required":["provider","externalLocationId","name","street1","street2","zip","city","country","latitude","longitude","distanceKm","openingHours"]},"Price":{"type":"object","properties":{"currency":{"type":"string"},"baseAmount":{"type":"string"},"surchargeAmount":{"type":"string"},"palletExchangeAmount":{"type":"string"},"taxAmount":{"type":"string"},"totalAmount":{"type":"string"}},"required":["currency","baseAmount","surchargeAmount","palletExchangeAmount","taxAmount","totalAmount"]},"AddressRecord":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40,"description":"Person or company name. Required and nonempty after trimming; see maxLength. Shipment services may impose a lower name limit."},"street1":{"type":"string","minLength":1,"maxLength":54,"description":"Primary street address, including house number. Required and nonempty after trimming; see maxLength and service fieldLimits."},"street2":{"default":null,"anyOf":[{"type":"string","maxLength":54},{"type":"null"}],"description":"Optional additional address line. Omit or send null to clear it; see maxLength and service fieldLimits."},"city":{"type":"string","minLength":1,"maxLength":30,"description":"Town or city. Required and nonempty after trimming; see maxLength."},"zip":{"type":"string","minLength":1,"maxLength":10,"description":"Postal code as text, preserving leading zeros. It must match the country for carrier shipments; see maxLength."},"country":{"type":"string","pattern":"^[A-Z]{2}$","description":"Supported country code in two-letter uppercase ISO format, such as DK. The country and service must have an available route and price."},"addressType":{"enum":["RESIDENTIAL","COMMERCIAL"],"type":"string","description":"RESIDENTIAL for a private address or COMMERCIAL for a business address."},"region":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional state, province, or region as text. Omit or send null to clear it."},"attention":{"default":null,"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"description":"Optional contact person or attention line. Omit or send null to clear it; see maxLength."},"email":{"default":null,"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"description":"Valid contact email address, or null. Required for a shipment receiver when GET /services reports receiverEmailRequired."},"phone":{"default":null,"anyOf":[{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$"},{"type":"null"}],"description":"Telephone number in international E.164 format, such as +4512345678, or null. Required for a shipment receiver when receiverPhoneRequired is true."},"mobile":{"default":null,"anyOf":[{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$"},{"type":"null"}],"description":"Mobile number in international E.164 format, such as +4512345678, or null. Required for a shipment receiver when receiverMobileRequired is true."},"id":{"type":"string","description":"Saved address ID belonging to the authenticated account."},"status":{"enum":["ACTIVE","ARCHIVED"],"type":"string","description":"ACTIVE or ARCHIVED address-book status. On update, omit to retain the current status. Changing an address does not rewrite shipment snapshots."},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when this saved address was created."}},"required":["name","street1","city","zip","country","addressType","id","status","createdAt"],"additionalProperties":false},"Shipment":{"type":"object","properties":{"id":{"type":"string"},"status":{"enum":["PENDING","PROCESSING","BOOKED","PICKED_UP","DELIVERED","CANCELED","FAILED"],"type":"string"},"serviceCode":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"pickupDate":{"type":"string"},"customerReference":{"anyOf":[{"type":"string"},{"type":"null"}]},"price":{"$ref":"#/components/schemas/Price"},"packages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"trackingNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"nationalTrackingNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"deliveryStatus":{"type":"string"}},"required":["id","type","trackingNumber","nationalTrackingNumber","deliveryStatus"]}},"labelReady":{"type":"boolean"}},"required":["id","status","serviceCode","createdAt","pickupDate","customerReference","price","packages","labelReady"]},"ServicePackage":{"type":"object","properties":{"type":{"type":"string","description":"Allowed packages[].type for this serviceCode."},"unit":{"enum":["KILOGRAM","QUANTITY"],"type":"string","description":"Pricing unit: by weight or by package count. Package weight is still supplied in kg."},"isPallet":{"type":"boolean","description":"Whether this package type represents a pallet."},"maxWeight":{"type":"number","description":"Maximum weight of one package in kg."},"maxHeight":{"type":"number","description":"Maximum package height in cm."},"maxWidth":{"type":"number","description":"Maximum package width in cm."},"maxLength":{"type":"number","description":"Maximum package length in cm."},"requiredPackageFields":{"type":"array","items":{"enum":["description","height"],"type":"string"},"description":"Fields that must be supplied for this package type. International volume-weight pricing can also require length, width, and height."}},"required":["type","unit","isPallet","maxWeight","maxHeight","maxWidth","maxLength","requiredPackageFields"]},"ShipmentPackage":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"trackingNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"nationalTrackingNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"deliveryStatus":{"type":"string"},"weight":{"type":"number"},"length":{"anyOf":[{"type":"number"},{"type":"null"}]},"width":{"anyOf":[{"type":"number"},{"type":"null"}]},"height":{"anyOf":[{"type":"number"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"hasDg":{"type":"boolean"},"dg":{"anyOf":[{"type":"object","properties":{"hazardClass":{"type":"string"},"unNumber":{"type":"string"},"properShippingName":{"type":"string"},"weight":{"type":"number"},"packingGroup":{"type":"string"},"flashPoint":{"anyOf":[{"type":"string"},{"type":"null"}]},"technicalName":{"anyOf":[{"type":"string"},{"type":"null"}]},"marinePollutant":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["hazardClass","unNumber","properShippingName","weight","packingGroup","flashPoint","technicalName","marinePollutant"]},{"type":"null"}]}},"required":["id","type","trackingNumber","nationalTrackingNumber","deliveryStatus","weight","length","width","height","description","hasDg","dg"]},"Error":{"type":"object","properties":{"success":{"const":false},"message":{"type":"string"},"data":{"type":"null"},"requestId":{"type":"string"},"errorCode":{"type":"string"},"errors":{"anyOf":[{"type":"object","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"errorCode":{"type":"string"},"message":{"type":"string"}},"required":["path","errorCode","message"]}},"price":{"$ref":"#/components/schemas/Price"},"currentStatus":{"type":"string"},"retryAfterSeconds":{"type":"integer","minimum":1}}},{"type":"null"}]}},"required":["success","message","data","requestId","errorCode","errors"]}}},"security":[{"customerKey":[]}],"openapi":"3.1.1","paths":{"/services":{"get":{"operationId":"services","summary":"List available services","description":"Lists available shipping services, package types, and service requirements.\n\n## Behavior\n\n- Availability depends on your account. Use the returned service and package types for shipment requests.\n\n\n## Permission\n\nAny valid Customer API key\n\nSee [Troubleshooting](/docs/api/reference/troubleshooting#common-errors) for authentication, access, rate-limit, and service errors.","tags":["services"],"responses":{"200":{"description":"Successful result","content":{"application/json":{"example":{"success":true,"message":"Available services retrieved.","data":{"services":[{"serviceCode":"BUSINESS_PARCEL","name":"Business Parcel","receiverMobileRequired":false,"receiverPhoneRequired":false,"receiverEmailRequired":false,"fieldLimits":{"maxNameLength":40,"maxStreet1Length":40,"maxStreet2Length":40,"maxCityLength":30,"maxContactLength":40,"maxZipCodeLength":10},"maxDescriptionLength":50,"packageTypes":[{"type":"BUSINESS_PARCEL","unit":"KILOGRAM","isPallet":false,"maxWeight":30,"maxHeight":60,"maxWidth":80,"maxLength":200,"requiredPackageFields":[]}]},{"serviceCode":"OTHER","name":"Other Shipment Type","receiverMobileRequired":false,"receiverPhoneRequired":false,"receiverEmailRequired":false,"fieldLimits":null,"maxDescriptionLength":50,"packageTypes":[]}]},"requestId":""},"schema":{"type":"object","required":["success","message","data","requestId"],"properties":{"success":{"const":true},"message":{"type":"string"},"data":{"type":"object","properties":{"services":{"type":"array","items":{"type":"object","properties":{"serviceCode":{"type":"string"},"name":{"type":"string"},"receiverMobileRequired":{"type":"boolean"},"receiverPhoneRequired":{"type":"boolean"},"receiverEmailRequired":{"type":"boolean"},"fieldLimits":{"type":["object","null"]},"maxDescriptionLength":{"type":"number"},"packageTypes":{"type":"array","items":{"$ref":"#/components/schemas/ServicePackage"}}}}}}},"requestId":{"type":"string"}}}}}},"400":{"description":"Invalid input or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Invalid input or unsupported operation.","data":null,"requestId":"request-id","errorCode":"BAD_REQUEST","errors":null}}}},"401":{"description":"Missing or invalid Customer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Missing or invalid Customer API key.","data":null,"requestId":"request-id","errorCode":"UNAUTHORIZED","errors":null}}}},"403":{"description":"Account API access unavailable or required permission missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account API access unavailable or required permission missing.","data":null,"requestId":"request-id","errorCode":"FORBIDDEN","errors":null}}}},"404":{"description":"Resource does not exist or belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Resource does not exist or belongs to another account.","data":null,"requestId":"request-id","errorCode":"NOT_FOUND","errors":null}}}},"429":{"description":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","data":null,"requestId":"request-id","errorCode":"TOO_MANY_REQUESTS","errors":{"retryAfterSeconds":30}}}}},"500":{"description":"Unexpected error. Contact support with requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Unexpected error. Contact support with requestId.","data":null,"requestId":"request-id","errorCode":"INTERNAL_SERVER_ERROR","errors":null}}}},"503":{"description":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","data":null,"requestId":"request-id","errorCode":"SERVICE_UNAVAILABLE","errors":null}}}}}}},"/prices":{"post":{"operationId":"prices","summary":"Preview shipment price","description":"Calculates a shipping price for the supplied shipment details.\n\n## Behavior\n\n- Uses the same sender, receiver, service, and package validation as draft creation.\n- Price previews do not create shipments.\n- Prices are two-decimal strings in DKK. A preview does not reserve the price.\n\n## Permission\n\nSHIPMENTS_READ\n\nSee [Troubleshooting](/docs/api/reference/troubleshooting#common-errors) for authentication, access, rate-limit, and service errors.","tags":["prices"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"serviceCode":{"enum":["PALLET","LEMAN_PALLET","BUSINESS_PARCEL","PRIVATE_PARCEL","PICKUP_SHIPMENT","SHOP_DELIVERY","DIRECT_SHOP","SHOP_RETURN","PICKUP_RETURN","GLOBAL_EXPRESS","EXPRESS_10","EXPRESS_12","OTHER"],"type":"string","description":"Choose a serviceCode returned by GET /services for this account. The enum lists recognized codes; availability depends on the account and route. OTHER has no carrier booking or printable label. Express services require pickup and delivery within Denmark."},"senderId":{"type":"string","minLength":1,"description":"Required ID of a saved sender belonging to this account. Obtain it from GET /senders or POST /senders."},"receiverId":{"type":"string","minLength":1,"description":"ID of a saved receiver belonging to this account. Provide exactly one of receiverId or receiver."},"receiver":{"$ref":"#/components/schemas/Address","description":"Inline receiver address instead of receiverId. Creating or replacing a draft saves it in the address book; price preview does not save it."},"pickupDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Valid YYYY-MM-DD date on the Copenhagen calendar. Carrier shipments cannot use a past date; OTHER still requires a valid date."},"packages":{"default":[],"type":"array","items":{"type":"object","properties":{"type":{"enum":["EURO_PALLET_QUARTER","EURO_PALLET_HALF","EURO_PALLET","PKK","LEMAN_EURO_PALLET_HALF","LEMAN_EURO_PALLET","INDUSTRIAL_PALLET","BUSINESS_PARCEL","PRIVATE_PARCEL","PICKUP_SHIPMENT","SHOP_DELIVERY","DIRECT_SHOP","SHOP_RETURN","PICKUP_RETURN","GLOBAL_EXPRESS","EXPRESS_10","EXPRESS_12","OTHER"],"type":"string","description":"Choose a packageTypes[].type returned by GET /services for the selected serviceCode. A recognized enum value is not necessarily enabled for this account."},"weight":{"type":"number","description":"Positive weight of this package in kg, no greater than the selected package type's maxWeight from GET /services.","exclusiveMinimum":0},"length":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}],"description":"Positive package length in cm, no greater than maxLength from GET /services. Required with width and height for international volume-weight pricing; otherwise may be omitted or null."},"width":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}],"description":"Positive package width in cm, no greater than maxWidth from GET /services. Required with length and height for international volume-weight pricing; otherwise may be omitted or null."},"height":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}],"description":"Positive package height in cm, no greater than maxHeight from GET /services. Required when listed in requiredPackageFields or for international volume-weight pricing; otherwise may be omitted or null."},"description":{"type":"string","description":"Package contents or goods description. Required when GET /services lists description in requiredPackageFields. Must not exceed the service's maxDescriptionLength."},"hasDg":{"type":"boolean","description":"Required boolean. Set true for dangerous goods and supply dg. Only GLS and LEMAN services support dangerous goods. Set false for ordinary goods and omit dg or send null."},"dg":{"default":null,"anyOf":[{"type":"object","properties":{"hazardClass":{"type":"string","minLength":1,"description":"Nonempty dangerous-goods hazard-class designation for the shipment."},"unNumber":{"type":"string","minLength":1,"pattern":"^\\d{4}$","description":"Four-digit UN number as a string without the UN prefix, such as 1234. Leading zeros are preserved."},"properShippingName":{"type":"string","minLength":1,"description":"Nonempty proper shipping name of the dangerous goods."},"weight":{"type":"number","description":"Positive weight of the dangerous goods in kg.","exclusiveMinimum":0},"packingGroup":{"type":"string","minLength":1,"description":"Nonempty packing-group designation as text, such as II, appropriate for the goods and carrier."},"flashPoint":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional flash-point value as text. Omit or send null when not needed."},"technicalName":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional technical or chemical name. Omit or send null when not needed."},"marinePollutant":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional marine-pollutant designation as text. Omit or send null when not needed."}},"required":["hazardClass","unNumber","properShippingName","weight","packingGroup"],"additionalProperties":false},{"type":"null"}],"description":"Dangerous-goods details, required when hasDg is true. Must be omitted or null when hasDg is false."}},"required":["type","weight","hasDg"],"additionalProperties":false},"description":"One item per physical package or pallet. At least one is required for carrier services. OTHER accepts an omitted or empty array. Each item requires type, positive weight, and hasDg."},"pickupLocation":{"anyOf":[{"type":"object","properties":{"externalLocationId":{"type":"string","minLength":1,"description":"Carrier's ID for the selected parcel shop, not a Bookogsend address-book ID."}},"required":["externalLocationId"],"additionalProperties":false},{"type":"null"}],"description":"Selected GLS parcel-shop ID. Required for SHOP_DELIVERY. Optional for other carrier services; ignored for OTHER. Bookogsend resolves the shop details and checks that the shop exists in the receiver country."},"isExchangePallets":{"type":"boolean","description":"Enable pallet exchange for serviceCode PALLET only; otherwise ignored. Defaults to false when omitted. If all exchange-count fields are omitted, eligible quarter, half, and full euro pallets are counted from packages."},"exchangePalletsQuarter":{"type":"integer","minimum":0,"maximum":99,"description":"Optional quarter-euro-pallet exchange count, integer 0–99, used with PALLET and isExchangePallets=true. Supplying any exchange count overrides automatic counting; omitted sizes count as zero."},"exchangePalletsHalf":{"type":"integer","minimum":0,"maximum":99,"description":"Optional half-euro-pallet exchange count, integer 0–99, used with PALLET and isExchangePallets=true. Supplying any exchange count overrides automatic counting; omitted sizes count as zero."},"exchangePalletsFull":{"type":"integer","minimum":0,"maximum":99,"description":"Optional full-euro-pallet exchange count, integer 0–99, used with PALLET and isExchangePallets=true. Supplying any exchange count overrides automatic counting; omitted sizes count as zero."}},"required":["serviceCode","senderId","pickupDate"],"additionalProperties":false},"example":{"serviceCode":"BUSINESS_PARCEL","senderId":"","receiverId":"","pickupDate":"2030-01-15","packages":[{"type":"BUSINESS_PARCEL","weight":1,"length":30,"width":20,"height":10,"hasDg":false}]}}},"description":"Shipment details for a price preview. This creates no draft and does not reserve the price."},"responses":{"200":{"description":"Successful result","content":{"application/json":{"example":{"success":true,"message":"Price calculated.","data":{"currency":"DKK","baseAmount":"100.00","surchargeAmount":"0.00","palletExchangeAmount":"0.00","taxAmount":"25.00","totalAmount":"125.00"},"requestId":""},"schema":{"type":"object","required":["success","message","data","requestId"],"properties":{"success":{"const":true},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Price"},"requestId":{"type":"string"}}}}}},"400":{"description":"Invalid shipment input, including an invalid GLS shop ID or receiver-country mismatch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation":{"value":{"success":false,"message":"Invalid input or unsupported operation.","data":null,"requestId":"request-id","errorCode":"BAD_REQUEST","errors":null}},"invalidPickupLocation":{"value":{"success":false,"message":"Select a valid GLS pickup location in the receiver country.","data":null,"requestId":"","errorCode":"INVALID_PICKUP_LOCATION","errors":{"fields":[{"path":"pickupLocation.externalLocationId","errorCode":"INVALID_PICKUP_LOCATION","message":"Select a valid GLS pickup location in the receiver country."}]}}}}}}},"401":{"description":"Missing or invalid Customer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Missing or invalid Customer API key.","data":null,"requestId":"request-id","errorCode":"UNAUTHORIZED","errors":null}}}},"403":{"description":"Account API access unavailable or required permission missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account API access unavailable or required permission missing.","data":null,"requestId":"request-id","errorCode":"FORBIDDEN","errors":null}}}},"404":{"description":"Resource does not exist or belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Resource does not exist or belongs to another account.","data":null,"requestId":"request-id","errorCode":"NOT_FOUND","errors":null}}}},"429":{"description":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","data":null,"requestId":"request-id","errorCode":"TOO_MANY_REQUESTS","errors":{"retryAfterSeconds":30}}}}},"500":{"description":"Unexpected error. Contact support with requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Unexpected error. Contact support with requestId.","data":null,"requestId":"request-id","errorCode":"INTERNAL_SERVER_ERROR","errors":null}}}},"503":{"description":"Pickup locations or receiver coordinates are temporarily unavailable. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Pickup locations are temporarily unavailable. Try again later.","data":null,"requestId":"","errorCode":"PICKUP_LOCATIONS_UNAVAILABLE","errors":null}}}}}}},"/senders":{"get":{"operationId":"senders.list","summary":"List senders","description":"Lists saved sender addresses.\n\n## Permission\n\nADDRESSES_READ\n\nSee [Troubleshooting](/docs/api/reference/troubleshooting#common-errors) for authentication, access, rate-limit, and service errors.","tags":["senders"],"parameters":[{"name":"pageSize","in":"query","schema":{"default":20,"type":"integer","minimum":1,"maximum":200},"allowEmptyValue":true,"allowReserved":true,"description":"Maximum records per page: 1–200, default 20. Results are newest first."},{"name":"cursor","in":"query","schema":{"type":"string","minLength":1},"allowEmptyValue":true,"allowReserved":true,"description":"Copy nextCursor from the previous response to fetch the next page. Keep the same filters; omit for the first page."},{"name":"filter","in":"query","schema":{"type":"string"},"allowEmptyValue":true,"allowReserved":true,"description":"Optional case-insensitive substring search across name, email, city, and postal code. Omit or send an empty string to disable search."},{"name":"status","in":"query","schema":{"enum":["ACTIVE","ARCHIVED"],"type":"string"},"allowEmptyValue":true,"allowReserved":true,"description":"Filter by ACTIVE or ARCHIVED address status. Omit to include both."}],"responses":{"200":{"description":"Successful result","content":{"application/json":{"example":{"success":true,"message":"Senders retrieved.","data":{"senders":[],"nextCursor":null},"requestId":""},"schema":{"type":"object","required":["success","message","data","requestId"],"properties":{"success":{"const":true},"message":{"type":"string"},"data":{"type":"object","properties":{"senders":{"type":"array","items":{"$ref":"#/components/schemas/AddressRecord"}},"nextCursor":{"type":["string","null"]}}},"requestId":{"type":"string"}}}}}},"400":{"description":"Invalid input or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Invalid input or unsupported operation.","data":null,"requestId":"request-id","errorCode":"BAD_REQUEST","errors":null}}}},"401":{"description":"Missing or invalid Customer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Missing or invalid Customer API key.","data":null,"requestId":"request-id","errorCode":"UNAUTHORIZED","errors":null}}}},"403":{"description":"Account API access unavailable or required permission missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account API access unavailable or required permission missing.","data":null,"requestId":"request-id","errorCode":"FORBIDDEN","errors":null}}}},"404":{"description":"Resource does not exist or belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Resource does not exist or belongs to another account.","data":null,"requestId":"request-id","errorCode":"NOT_FOUND","errors":null}}}},"429":{"description":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","data":null,"requestId":"request-id","errorCode":"TOO_MANY_REQUESTS","errors":{"retryAfterSeconds":30}}}}},"500":{"description":"Unexpected error. Contact support with requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Unexpected error. Contact support with requestId.","data":null,"requestId":"request-id","errorCode":"INTERNAL_SERVER_ERROR","errors":null}}}},"503":{"description":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","data":null,"requestId":"request-id","errorCode":"SERVICE_UNAVAILABLE","errors":null}}}}}},"post":{"operationId":"senders.create","summary":"Create sender","description":"Saves a sender address for reuse in shipment requests.\n\n## Permission\n\nADDRESSES_WRITE\n\nSee [Troubleshooting](/docs/api/reference/troubleshooting#common-errors) for authentication, access, rate-limit, and service errors.","tags":["senders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Address"},"example":{"name":"Example Company","street1":"Østerbrogade 1","city":"København Ø","zip":"2100","country":"DK","addressType":"COMMERCIAL"}}},"description":"Address details to save in this account's address book. Required fields and length limits are shown in the schema."},"responses":{"201":{"description":"Successful result","content":{"application/json":{"example":{"success":true,"message":"Sender created.","data":{"name":"Example Company","street1":"Østerbrogade 1","city":"København Ø","zip":"2100","country":"DK","addressType":"COMMERCIAL","street2":null,"region":null,"attention":null,"email":null,"phone":null,"mobile":null,"id":"","status":"ACTIVE","createdAt":"2030-01-01T10:00:00.000Z"},"requestId":""},"schema":{"type":"object","required":["success","message","data","requestId"],"properties":{"success":{"const":true},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/AddressRecord"},"requestId":{"type":"string"}}}}}},"400":{"description":"Invalid input or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Invalid input or unsupported operation.","data":null,"requestId":"request-id","errorCode":"BAD_REQUEST","errors":null}}}},"401":{"description":"Missing or invalid Customer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Missing or invalid Customer API key.","data":null,"requestId":"request-id","errorCode":"UNAUTHORIZED","errors":null}}}},"403":{"description":"Account API access unavailable or required permission missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account API access unavailable or required permission missing.","data":null,"requestId":"request-id","errorCode":"FORBIDDEN","errors":null}}}},"404":{"description":"Resource does not exist or belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Resource does not exist or belongs to another account.","data":null,"requestId":"request-id","errorCode":"NOT_FOUND","errors":null}}}},"409":{"description":"State, idempotency, price, or label conflict; inspect errorCode and errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"State, idempotency, price, or label conflict; inspect errorCode and errors.","data":null,"requestId":"request-id","errorCode":"IDEMPOTENCY_KEY_REUSED","errors":null}}}},"429":{"description":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","data":null,"requestId":"request-id","errorCode":"TOO_MANY_REQUESTS","errors":{"retryAfterSeconds":30}}}}},"500":{"description":"Unexpected error. Contact support with requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Unexpected error. Contact support with requestId.","data":null,"requestId":"request-id","errorCode":"INTERNAL_SERVER_ERROR","errors":null}}}},"503":{"description":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","data":null,"requestId":"request-id","errorCode":"SERVICE_UNAVAILABLE","errors":null}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Unique operation key, at most 255 characters after trimming. Retry the same request with the same key; use a new key for a changed request.","example":""}]}},"/senders/{id}":{"get":{"operationId":"senders.get","summary":"Get sender details","description":"Retrieves a saved sender address.\n\n## Permission\n\nADDRESSES_READ\n\nSee [Troubleshooting](/docs/api/reference/troubleshooting#common-errors) for authentication, access, rate-limit, and service errors.","tags":["senders"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"ID of the sender. Obtain it from a list or create response. Unavailable IDs return 404.","example":""}],"responses":{"200":{"description":"Successful result","content":{"application/json":{"example":{"success":true,"message":"Sender retrieved.","data":{"name":"Example Company","street1":"Østerbrogade 1","city":"København Ø","zip":"2100","country":"DK","addressType":"COMMERCIAL","street2":null,"region":null,"attention":null,"email":null,"phone":null,"mobile":null,"id":"","status":"ACTIVE","createdAt":"2030-01-01T10:00:00.000Z"},"requestId":""},"schema":{"type":"object","required":["success","message","data","requestId"],"properties":{"success":{"const":true},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/AddressRecord"},"requestId":{"type":"string"}}}}}},"400":{"description":"Invalid input or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Invalid input or unsupported operation.","data":null,"requestId":"request-id","errorCode":"BAD_REQUEST","errors":null}}}},"401":{"description":"Missing or invalid Customer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Missing or invalid Customer API key.","data":null,"requestId":"request-id","errorCode":"UNAUTHORIZED","errors":null}}}},"403":{"description":"Account API access unavailable or required permission missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account API access unavailable or required permission missing.","data":null,"requestId":"request-id","errorCode":"FORBIDDEN","errors":null}}}},"404":{"description":"Resource does not exist or belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Resource does not exist or belongs to another account.","data":null,"requestId":"request-id","errorCode":"NOT_FOUND","errors":null}}}},"429":{"description":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","data":null,"requestId":"request-id","errorCode":"TOO_MANY_REQUESTS","errors":{"retryAfterSeconds":30}}}}},"500":{"description":"Unexpected error. Contact support with requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Unexpected error. Contact support with requestId.","data":null,"requestId":"request-id","errorCode":"INTERNAL_SERVER_ERROR","errors":null}}}},"503":{"description":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","data":null,"requestId":"request-id","errorCode":"SERVICE_UNAVAILABLE","errors":null}}}}}},"put":{"operationId":"senders.update","summary":"Update sender","description":"Updates a saved sender address.\n\n## Behavior\n\n- Send the complete address, including all required fields and optional values you want to keep. This is not a partial update.\n- Optional address fields left out are cleared. For example, leaving out `email` removes the saved email.\n- Send `status` only when changing it. Otherwise, its current value is kept.\n- Existing shipment snapshots remain unchanged.\n\n## Permission\n\nADDRESSES_WRITE\n\nSee [Troubleshooting](/docs/api/reference/troubleshooting#common-errors) for authentication, access, rate-limit, and service errors.","tags":["senders"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"ID of the sender. Obtain it from a list or create response. Unavailable IDs return 404.","example":""},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Unique operation key, at most 255 characters after trimming. Retry the same request with the same key; use a new key for a changed request.","example":""}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40,"description":"Person or company name. Required and nonempty after trimming; see maxLength. Shipment services may impose a lower name limit."},"street1":{"type":"string","minLength":1,"maxLength":54,"description":"Primary street address, including house number. Required and nonempty after trimming; see maxLength and service fieldLimits."},"street2":{"default":null,"anyOf":[{"type":"string","maxLength":54},{"type":"null"}],"description":"Optional additional address line. Omit or send null to clear it; see maxLength and service fieldLimits."},"city":{"type":"string","minLength":1,"maxLength":30,"description":"Town or city. Required and nonempty after trimming; see maxLength."},"zip":{"type":"string","minLength":1,"maxLength":10,"description":"Postal code as text, preserving leading zeros. It must match the country for carrier shipments; see maxLength."},"country":{"type":"string","pattern":"^[A-Z]{2}$","description":"Supported country code in two-letter uppercase ISO format, such as DK. The country and service must have an available route and price."},"addressType":{"enum":["RESIDENTIAL","COMMERCIAL"],"type":"string","description":"RESIDENTIAL for a private address or COMMERCIAL for a business address."},"region":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional state, province, or region as text. Omit or send null to clear it."},"attention":{"default":null,"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"description":"Optional contact person or attention line. Omit or send null to clear it; see maxLength."},"email":{"default":null,"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"description":"Valid contact email address, or null. Required for a shipment receiver when GET /services reports receiverEmailRequired."},"phone":{"default":null,"anyOf":[{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$"},{"type":"null"}],"description":"Telephone number in international E.164 format, such as +4512345678, or null. Required for a shipment receiver when receiverPhoneRequired is true."},"mobile":{"default":null,"anyOf":[{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$"},{"type":"null"}],"description":"Mobile number in international E.164 format, such as +4512345678, or null. Required for a shipment receiver when receiverMobileRequired is true."},"status":{"enum":["ACTIVE","ARCHIVED"],"type":"string","description":"ACTIVE or ARCHIVED address-book status. On update, omit to retain the current status. Changing an address does not rewrite shipment snapshots."}},"required":["name","street1","city","zip","country","addressType"],"additionalProperties":false},"example":{"name":"Example Company","street1":"Østerbrogade 1","city":"København Ø","zip":"2100","country":"DK","addressType":"COMMERCIAL"}}},"description":"Complete address to save. Send all required fields and optional values you want to keep."},"responses":{"200":{"description":"Successful result","content":{"application/json":{"example":{"success":true,"message":"Sender updated.","data":{"name":"Example Company","street1":"Østerbrogade 1","city":"København Ø","zip":"2100","country":"DK","addressType":"COMMERCIAL","street2":null,"region":null,"attention":null,"email":null,"phone":null,"mobile":null,"id":"","status":"ACTIVE","createdAt":"2030-01-01T10:00:00.000Z"},"requestId":""},"schema":{"type":"object","required":["success","message","data","requestId"],"properties":{"success":{"const":true},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/AddressRecord"},"requestId":{"type":"string"}}}}}},"400":{"description":"Invalid input or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Invalid input or unsupported operation.","data":null,"requestId":"request-id","errorCode":"BAD_REQUEST","errors":null}}}},"401":{"description":"Missing or invalid Customer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Missing or invalid Customer API key.","data":null,"requestId":"request-id","errorCode":"UNAUTHORIZED","errors":null}}}},"403":{"description":"Account API access unavailable or required permission missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account API access unavailable or required permission missing.","data":null,"requestId":"request-id","errorCode":"FORBIDDEN","errors":null}}}},"404":{"description":"Resource does not exist or belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Resource does not exist or belongs to another account.","data":null,"requestId":"request-id","errorCode":"NOT_FOUND","errors":null}}}},"409":{"description":"State, idempotency, price, or label conflict; inspect errorCode and errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"State, idempotency, price, or label conflict; inspect errorCode and errors.","data":null,"requestId":"request-id","errorCode":"IDEMPOTENCY_KEY_REUSED","errors":null}}}},"429":{"description":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","data":null,"requestId":"request-id","errorCode":"TOO_MANY_REQUESTS","errors":{"retryAfterSeconds":30}}}}},"500":{"description":"Unexpected error. Contact support with requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Unexpected error. Contact support with requestId.","data":null,"requestId":"request-id","errorCode":"INTERNAL_SERVER_ERROR","errors":null}}}},"503":{"description":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","data":null,"requestId":"request-id","errorCode":"SERVICE_UNAVAILABLE","errors":null}}}}}},"delete":{"operationId":"senders.delete","summary":"Delete sender","description":"Deletes a saved sender address.\n\n## Prerequisites\n\n- The address must have no associated shipments.\n- The sender must not be the account's default sender.\n\n## Permission\n\nADDRESSES_WRITE\n\nSee [Troubleshooting](/docs/api/reference/troubleshooting#common-errors) for authentication, access, rate-limit, and service errors.","tags":["senders"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"ID of the sender. Obtain it from a list or create response. Unavailable IDs return 404.","example":""},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Unique operation key, at most 255 characters after trimming. Retry the same request with the same key; use a new key for a changed request.","example":""}],"responses":{"200":{"description":"Successful result","content":{"application/json":{"example":{"success":true,"message":"Sender deleted.","data":null,"requestId":""},"schema":{"type":"object","required":["success","message","data","requestId"],"properties":{"success":{"const":true},"message":{"type":"string"},"data":{"type":"null"},"requestId":{"type":"string"}}}}}},"400":{"description":"Invalid input or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Invalid input or unsupported operation.","data":null,"requestId":"request-id","errorCode":"BAD_REQUEST","errors":null}}}},"401":{"description":"Missing or invalid Customer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Missing or invalid Customer API key.","data":null,"requestId":"request-id","errorCode":"UNAUTHORIZED","errors":null}}}},"403":{"description":"Account API access unavailable or required permission missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account API access unavailable or required permission missing.","data":null,"requestId":"request-id","errorCode":"FORBIDDEN","errors":null}}}},"404":{"description":"Resource does not exist or belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Resource does not exist or belongs to another account.","data":null,"requestId":"request-id","errorCode":"NOT_FOUND","errors":null}}}},"409":{"description":"State, idempotency, price, or label conflict; inspect errorCode and errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"State, idempotency, price, or label conflict; inspect errorCode and errors.","data":null,"requestId":"request-id","errorCode":"IDEMPOTENCY_KEY_REUSED","errors":null}}}},"429":{"description":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","data":null,"requestId":"request-id","errorCode":"TOO_MANY_REQUESTS","errors":{"retryAfterSeconds":30}}}}},"500":{"description":"Unexpected error. Contact support with requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Unexpected error. Contact support with requestId.","data":null,"requestId":"request-id","errorCode":"INTERNAL_SERVER_ERROR","errors":null}}}},"503":{"description":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","data":null,"requestId":"request-id","errorCode":"SERVICE_UNAVAILABLE","errors":null}}}}}}},"/receivers":{"get":{"operationId":"receivers.list","summary":"List receivers","description":"Lists saved receiver addresses.\n\n## Permission\n\nADDRESSES_READ\n\nSee [Troubleshooting](/docs/api/reference/troubleshooting#common-errors) for authentication, access, rate-limit, and service errors.","tags":["receivers"],"parameters":[{"name":"pageSize","in":"query","schema":{"default":20,"type":"integer","minimum":1,"maximum":200},"allowEmptyValue":true,"allowReserved":true,"description":"Maximum records per page: 1–200, default 20. Results are newest first."},{"name":"cursor","in":"query","schema":{"type":"string","minLength":1},"allowEmptyValue":true,"allowReserved":true,"description":"Copy nextCursor from the previous response to fetch the next page. Keep the same filters; omit for the first page."},{"name":"filter","in":"query","schema":{"type":"string"},"allowEmptyValue":true,"allowReserved":true,"description":"Optional case-insensitive substring search across name, email, city, and postal code. Omit or send an empty string to disable search."},{"name":"status","in":"query","schema":{"enum":["ACTIVE","ARCHIVED"],"type":"string"},"allowEmptyValue":true,"allowReserved":true,"description":"Filter by ACTIVE or ARCHIVED address status. Omit to include both."}],"responses":{"200":{"description":"Successful result","content":{"application/json":{"example":{"success":true,"message":"Receivers retrieved.","data":{"receivers":[],"nextCursor":null},"requestId":""},"schema":{"type":"object","required":["success","message","data","requestId"],"properties":{"success":{"const":true},"message":{"type":"string"},"data":{"type":"object","properties":{"receivers":{"type":"array","items":{"$ref":"#/components/schemas/AddressRecord"}},"nextCursor":{"type":["string","null"]}}},"requestId":{"type":"string"}}}}}},"400":{"description":"Invalid input or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Invalid input or unsupported operation.","data":null,"requestId":"request-id","errorCode":"BAD_REQUEST","errors":null}}}},"401":{"description":"Missing or invalid Customer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Missing or invalid Customer API key.","data":null,"requestId":"request-id","errorCode":"UNAUTHORIZED","errors":null}}}},"403":{"description":"Account API access unavailable or required permission missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account API access unavailable or required permission missing.","data":null,"requestId":"request-id","errorCode":"FORBIDDEN","errors":null}}}},"404":{"description":"Resource does not exist or belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Resource does not exist or belongs to another account.","data":null,"requestId":"request-id","errorCode":"NOT_FOUND","errors":null}}}},"429":{"description":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","data":null,"requestId":"request-id","errorCode":"TOO_MANY_REQUESTS","errors":{"retryAfterSeconds":30}}}}},"500":{"description":"Unexpected error. Contact support with requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Unexpected error. Contact support with requestId.","data":null,"requestId":"request-id","errorCode":"INTERNAL_SERVER_ERROR","errors":null}}}},"503":{"description":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","data":null,"requestId":"request-id","errorCode":"SERVICE_UNAVAILABLE","errors":null}}}}}},"post":{"operationId":"receivers.create","summary":"Create receiver","description":"Saves a receiver address for reuse in shipment requests.\n\n## Permission\n\nADDRESSES_WRITE\n\nSee [Troubleshooting](/docs/api/reference/troubleshooting#common-errors) for authentication, access, rate-limit, and service errors.","tags":["receivers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Address"},"example":{"name":"Example Company","street1":"Østerbrogade 1","city":"København Ø","zip":"2100","country":"DK","addressType":"COMMERCIAL"}}},"description":"Address details to save in this account's address book. Required fields and length limits are shown in the schema."},"responses":{"201":{"description":"Successful result","content":{"application/json":{"example":{"success":true,"message":"Receiver created.","data":{"name":"Example Company","street1":"Østerbrogade 1","city":"København Ø","zip":"2100","country":"DK","addressType":"COMMERCIAL","street2":null,"region":null,"attention":null,"email":null,"phone":null,"mobile":null,"id":"","status":"ACTIVE","createdAt":"2030-01-01T10:00:00.000Z"},"requestId":""},"schema":{"type":"object","required":["success","message","data","requestId"],"properties":{"success":{"const":true},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/AddressRecord"},"requestId":{"type":"string"}}}}}},"400":{"description":"Invalid input or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Invalid input or unsupported operation.","data":null,"requestId":"request-id","errorCode":"BAD_REQUEST","errors":null}}}},"401":{"description":"Missing or invalid Customer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Missing or invalid Customer API key.","data":null,"requestId":"request-id","errorCode":"UNAUTHORIZED","errors":null}}}},"403":{"description":"Account API access unavailable or required permission missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account API access unavailable or required permission missing.","data":null,"requestId":"request-id","errorCode":"FORBIDDEN","errors":null}}}},"404":{"description":"Resource does not exist or belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Resource does not exist or belongs to another account.","data":null,"requestId":"request-id","errorCode":"NOT_FOUND","errors":null}}}},"409":{"description":"State, idempotency, price, or label conflict; inspect errorCode and errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"State, idempotency, price, or label conflict; inspect errorCode and errors.","data":null,"requestId":"request-id","errorCode":"IDEMPOTENCY_KEY_REUSED","errors":null}}}},"429":{"description":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","data":null,"requestId":"request-id","errorCode":"TOO_MANY_REQUESTS","errors":{"retryAfterSeconds":30}}}}},"500":{"description":"Unexpected error. Contact support with requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Unexpected error. Contact support with requestId.","data":null,"requestId":"request-id","errorCode":"INTERNAL_SERVER_ERROR","errors":null}}}},"503":{"description":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","data":null,"requestId":"request-id","errorCode":"SERVICE_UNAVAILABLE","errors":null}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Unique operation key, at most 255 characters after trimming. Retry the same request with the same key; use a new key for a changed request.","example":""}]}},"/receivers/{id}":{"get":{"operationId":"receivers.get","summary":"Get receiver details","description":"Retrieves a saved receiver address.\n\n## Permission\n\nADDRESSES_READ\n\nSee [Troubleshooting](/docs/api/reference/troubleshooting#common-errors) for authentication, access, rate-limit, and service errors.","tags":["receivers"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"ID of the receiver. Obtain it from a list or create response. Unavailable IDs return 404.","example":""}],"responses":{"200":{"description":"Successful result","content":{"application/json":{"example":{"success":true,"message":"Receiver retrieved.","data":{"name":"Example Company","street1":"Østerbrogade 1","city":"København Ø","zip":"2100","country":"DK","addressType":"COMMERCIAL","street2":null,"region":null,"attention":null,"email":null,"phone":null,"mobile":null,"id":"","status":"ACTIVE","createdAt":"2030-01-01T10:00:00.000Z"},"requestId":""},"schema":{"type":"object","required":["success","message","data","requestId"],"properties":{"success":{"const":true},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/AddressRecord"},"requestId":{"type":"string"}}}}}},"400":{"description":"Invalid input or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Invalid input or unsupported operation.","data":null,"requestId":"request-id","errorCode":"BAD_REQUEST","errors":null}}}},"401":{"description":"Missing or invalid Customer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Missing or invalid Customer API key.","data":null,"requestId":"request-id","errorCode":"UNAUTHORIZED","errors":null}}}},"403":{"description":"Account API access unavailable or required permission missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account API access unavailable or required permission missing.","data":null,"requestId":"request-id","errorCode":"FORBIDDEN","errors":null}}}},"404":{"description":"Resource does not exist or belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Resource does not exist or belongs to another account.","data":null,"requestId":"request-id","errorCode":"NOT_FOUND","errors":null}}}},"429":{"description":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","data":null,"requestId":"request-id","errorCode":"TOO_MANY_REQUESTS","errors":{"retryAfterSeconds":30}}}}},"500":{"description":"Unexpected error. Contact support with requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Unexpected error. Contact support with requestId.","data":null,"requestId":"request-id","errorCode":"INTERNAL_SERVER_ERROR","errors":null}}}},"503":{"description":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","data":null,"requestId":"request-id","errorCode":"SERVICE_UNAVAILABLE","errors":null}}}}}},"put":{"operationId":"receivers.update","summary":"Update receiver","description":"Updates a saved receiver address.\n\n## Behavior\n\n- Send the complete address, including all required fields and optional values you want to keep. This is not a partial update.\n- Optional address fields left out are cleared. For example, leaving out `email` removes the saved email.\n- Send `status` only when changing it. Otherwise, its current value is kept.\n- Existing shipment snapshots remain unchanged.\n\n## Permission\n\nADDRESSES_WRITE\n\nSee [Troubleshooting](/docs/api/reference/troubleshooting#common-errors) for authentication, access, rate-limit, and service errors.","tags":["receivers"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"ID of the receiver. Obtain it from a list or create response. Unavailable IDs return 404.","example":""},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Unique operation key, at most 255 characters after trimming. Retry the same request with the same key; use a new key for a changed request.","example":""}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40,"description":"Person or company name. Required and nonempty after trimming; see maxLength. Shipment services may impose a lower name limit."},"street1":{"type":"string","minLength":1,"maxLength":54,"description":"Primary street address, including house number. Required and nonempty after trimming; see maxLength and service fieldLimits."},"street2":{"default":null,"anyOf":[{"type":"string","maxLength":54},{"type":"null"}],"description":"Optional additional address line. Omit or send null to clear it; see maxLength and service fieldLimits."},"city":{"type":"string","minLength":1,"maxLength":30,"description":"Town or city. Required and nonempty after trimming; see maxLength."},"zip":{"type":"string","minLength":1,"maxLength":10,"description":"Postal code as text, preserving leading zeros. It must match the country for carrier shipments; see maxLength."},"country":{"type":"string","pattern":"^[A-Z]{2}$","description":"Supported country code in two-letter uppercase ISO format, such as DK. The country and service must have an available route and price."},"addressType":{"enum":["RESIDENTIAL","COMMERCIAL"],"type":"string","description":"RESIDENTIAL for a private address or COMMERCIAL for a business address."},"region":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional state, province, or region as text. Omit or send null to clear it."},"attention":{"default":null,"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"description":"Optional contact person or attention line. Omit or send null to clear it; see maxLength."},"email":{"default":null,"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"description":"Valid contact email address, or null. Required for a shipment receiver when GET /services reports receiverEmailRequired."},"phone":{"default":null,"anyOf":[{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$"},{"type":"null"}],"description":"Telephone number in international E.164 format, such as +4512345678, or null. Required for a shipment receiver when receiverPhoneRequired is true."},"mobile":{"default":null,"anyOf":[{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$"},{"type":"null"}],"description":"Mobile number in international E.164 format, such as +4512345678, or null. Required for a shipment receiver when receiverMobileRequired is true."},"status":{"enum":["ACTIVE","ARCHIVED"],"type":"string","description":"ACTIVE or ARCHIVED address-book status. On update, omit to retain the current status. Changing an address does not rewrite shipment snapshots."}},"required":["name","street1","city","zip","country","addressType"],"additionalProperties":false},"example":{"name":"Example Company","street1":"Østerbrogade 1","city":"København Ø","zip":"2100","country":"DK","addressType":"COMMERCIAL"}}},"description":"Complete address to save. Send all required fields and optional values you want to keep."},"responses":{"200":{"description":"Successful result","content":{"application/json":{"example":{"success":true,"message":"Receiver updated.","data":{"name":"Example Company","street1":"Østerbrogade 1","city":"København Ø","zip":"2100","country":"DK","addressType":"COMMERCIAL","street2":null,"region":null,"attention":null,"email":null,"phone":null,"mobile":null,"id":"","status":"ACTIVE","createdAt":"2030-01-01T10:00:00.000Z"},"requestId":""},"schema":{"type":"object","required":["success","message","data","requestId"],"properties":{"success":{"const":true},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/AddressRecord"},"requestId":{"type":"string"}}}}}},"400":{"description":"Invalid input or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Invalid input or unsupported operation.","data":null,"requestId":"request-id","errorCode":"BAD_REQUEST","errors":null}}}},"401":{"description":"Missing or invalid Customer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Missing or invalid Customer API key.","data":null,"requestId":"request-id","errorCode":"UNAUTHORIZED","errors":null}}}},"403":{"description":"Account API access unavailable or required permission missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account API access unavailable or required permission missing.","data":null,"requestId":"request-id","errorCode":"FORBIDDEN","errors":null}}}},"404":{"description":"Resource does not exist or belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Resource does not exist or belongs to another account.","data":null,"requestId":"request-id","errorCode":"NOT_FOUND","errors":null}}}},"409":{"description":"State, idempotency, price, or label conflict; inspect errorCode and errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"State, idempotency, price, or label conflict; inspect errorCode and errors.","data":null,"requestId":"request-id","errorCode":"IDEMPOTENCY_KEY_REUSED","errors":null}}}},"429":{"description":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","data":null,"requestId":"request-id","errorCode":"TOO_MANY_REQUESTS","errors":{"retryAfterSeconds":30}}}}},"500":{"description":"Unexpected error. Contact support with requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Unexpected error. Contact support with requestId.","data":null,"requestId":"request-id","errorCode":"INTERNAL_SERVER_ERROR","errors":null}}}},"503":{"description":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","data":null,"requestId":"request-id","errorCode":"SERVICE_UNAVAILABLE","errors":null}}}}}},"delete":{"operationId":"receivers.delete","summary":"Delete receiver","description":"Deletes a saved receiver address.\n\n## Prerequisites\n\n- The address must have no associated shipments.\n\n## Permission\n\nADDRESSES_WRITE\n\nSee [Troubleshooting](/docs/api/reference/troubleshooting#common-errors) for authentication, access, rate-limit, and service errors.","tags":["receivers"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"ID of the receiver. Obtain it from a list or create response. Unavailable IDs return 404.","example":""},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Unique operation key, at most 255 characters after trimming. Retry the same request with the same key; use a new key for a changed request.","example":""}],"responses":{"200":{"description":"Successful result","content":{"application/json":{"example":{"success":true,"message":"Receiver deleted.","data":null,"requestId":""},"schema":{"type":"object","required":["success","message","data","requestId"],"properties":{"success":{"const":true},"message":{"type":"string"},"data":{"type":"null"},"requestId":{"type":"string"}}}}}},"400":{"description":"Invalid input or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Invalid input or unsupported operation.","data":null,"requestId":"request-id","errorCode":"BAD_REQUEST","errors":null}}}},"401":{"description":"Missing or invalid Customer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Missing or invalid Customer API key.","data":null,"requestId":"request-id","errorCode":"UNAUTHORIZED","errors":null}}}},"403":{"description":"Account API access unavailable or required permission missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account API access unavailable or required permission missing.","data":null,"requestId":"request-id","errorCode":"FORBIDDEN","errors":null}}}},"404":{"description":"Resource does not exist or belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Resource does not exist or belongs to another account.","data":null,"requestId":"request-id","errorCode":"NOT_FOUND","errors":null}}}},"409":{"description":"State, idempotency, price, or label conflict; inspect errorCode and errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"State, idempotency, price, or label conflict; inspect errorCode and errors.","data":null,"requestId":"request-id","errorCode":"IDEMPOTENCY_KEY_REUSED","errors":null}}}},"429":{"description":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","data":null,"requestId":"request-id","errorCode":"TOO_MANY_REQUESTS","errors":{"retryAfterSeconds":30}}}}},"500":{"description":"Unexpected error. Contact support with requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Unexpected error. Contact support with requestId.","data":null,"requestId":"request-id","errorCode":"INTERNAL_SERVER_ERROR","errors":null}}}},"503":{"description":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","data":null,"requestId":"request-id","errorCode":"SERVICE_UNAVAILABLE","errors":null}}}}}}},"/pickup-locations":{"get":{"operationId":"pickupLocations","summary":"Find GLS pickup locations","description":"Finds GLS parcel shops for a receiver address.\n\n## Behavior\n\n- Accepts receiver address fields as query parameters. Unknown query fields are rejected.\n- Searches for 20 nearest shops. If that search returns no shops, the fallback can return all shops in the receiver country.\n- Returns `data.pickupLocations` ordered by receiver-relative straight-line `distanceKm`, nearest first. Distance is in kilometres, not driving distance.\n- An empty array means no shops were found. This response has no pagination cursor.\n- `503 PICKUP_LOCATIONS_UNAVAILABLE` means lookup failed or receiver coordinates could not be obtained. Retry later.\n- Does not require an idempotency key or create a shipment. See [Select a pickup location](/docs/api/guides/pickup-locations) to send the selected shop ID in price and shipment requests.\n\n## Permission\n\nSHIPMENTS_READ\n\nSee [Troubleshooting](/docs/api/reference/troubleshooting#common-errors) for authentication, access, rate-limit, and service errors.","tags":["pickup-locations"],"parameters":[{"name":"street1","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":54},"example":"Østerbrogade 1","description":"Receiver's primary street address, including house number. Required and nonempty after trimming; see maxLength."},{"name":"street2","in":"query","required":false,"schema":{"type":"string","maxLength":54},"description":"Optional second address line for the receiver. Omit when unused; see maxLength."},{"name":"city","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":30},"example":"København Ø","description":"Receiver's town or city. Required and nonempty after trimming; see maxLength."},{"name":"region","in":"query","required":false,"schema":{"type":"string"},"description":"Optional receiver state, province, or region. Omit when unused."},{"name":"zip","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":10},"example":"2100","description":"Receiver's postal code as text, preserving leading zeros. Required and nonempty after trimming; see maxLength."},{"name":"country","in":"query","required":true,"schema":{"type":"string","pattern":"^[A-Z]{2}$"},"example":"DK","description":"Receiver's recognized two-letter uppercase country code, such as DK. Results contain only shops in this country."}],"responses":{"200":{"description":"Successful result","content":{"application/json":{"example":{"success":true,"message":"Pickup locations retrieved.","data":{"pickupLocations":[{"provider":"GLS","externalLocationId":"","name":"Example GLS parcel shop","street1":"Example Street 2","street2":"","zip":"2100","city":"København Ø","country":"DK","latitude":55.7,"longitude":12.58,"distanceKm":0.45,"openingHours":[{"weekdayISO8601":1,"timeWindows":[{"fromISO8601":"09:00","toISO8601":"18:00"}]}]}]},"requestId":""},"schema":{"type":"object","required":["success","message","data","requestId"],"properties":{"success":{"const":true},"message":{"type":"string"},"data":{"type":"object","required":["pickupLocations"],"properties":{"pickupLocations":{"type":"array","items":{"$ref":"#/components/schemas/PickupLocation"}}}},"requestId":{"type":"string"}}}}}},"400":{"description":"Invalid input or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Invalid input or unsupported operation.","data":null,"requestId":"request-id","errorCode":"BAD_REQUEST","errors":null}}}},"401":{"description":"Missing or invalid Customer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Missing or invalid Customer API key.","data":null,"requestId":"request-id","errorCode":"UNAUTHORIZED","errors":null}}}},"403":{"description":"Account API access unavailable or required permission missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account API access unavailable or required permission missing.","data":null,"requestId":"request-id","errorCode":"FORBIDDEN","errors":null}}}},"429":{"description":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","data":null,"requestId":"request-id","errorCode":"TOO_MANY_REQUESTS","errors":{"retryAfterSeconds":30}}}}},"500":{"description":"Unexpected error. Contact support with requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Unexpected error. Contact support with requestId.","data":null,"requestId":"request-id","errorCode":"INTERNAL_SERVER_ERROR","errors":null}}}},"503":{"description":"Pickup locations or receiver coordinates are temporarily unavailable. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Pickup locations are temporarily unavailable. Try again later.","data":null,"requestId":"","errorCode":"PICKUP_LOCATIONS_UNAVAILABLE","errors":null}}}}}}},"/shipments/{id}/label":{"get":{"operationId":"shipments.label","summary":"Download shipment label","description":"Downloads the shipment's existing PDF label through a signed URL.\n\n## Prerequisites\n\n- The service must support printable labels.\n- The shipment must be `BOOKED`, `PICKED_UP`, or `DELIVERED`.\n- A PDF label must already exist.\n\n## Behavior\n\n- Follow the `302 Location` redirect. The URL expires after five minutes; request a fresh URL when needed.\n- This endpoint does not book shipments or regenerate labels.\n- `labelReady` indicates lifecycle readiness. It does not check whether the PDF exists.\n- `409 LABEL_NOT_READY` means the shipment or PDF is not ready. `400 LABEL_NOT_SUPPORTED` means the service has no printable label.\n\n## Permission\n\nSHIPMENTS_READ\n\nSee [Troubleshooting](/docs/api/reference/troubleshooting#common-errors) for authentication, access, rate-limit, and service errors.","tags":["shipments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"ID of the shipment. Obtain it from a list or create response. Unavailable IDs return 404.","example":""}],"responses":{"302":{"description":"Redirect to the existing PDF label. Signed URL expires after five minutes; fetch a fresh URL rather than storing it.","headers":{"Location":{"schema":{"type":"string","format":"uri"}}}},"400":{"description":"Invalid input or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Invalid input or unsupported operation.","data":null,"requestId":"request-id","errorCode":"BAD_REQUEST","errors":null}}}},"401":{"description":"Missing or invalid Customer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Missing or invalid Customer API key.","data":null,"requestId":"request-id","errorCode":"UNAUTHORIZED","errors":null}}}},"403":{"description":"Account API access unavailable or required permission missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account API access unavailable or required permission missing.","data":null,"requestId":"request-id","errorCode":"FORBIDDEN","errors":null}}}},"404":{"description":"Resource does not exist or belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Resource does not exist or belongs to another account.","data":null,"requestId":"request-id","errorCode":"NOT_FOUND","errors":null}}}},"409":{"description":"Label is not ready or its PDF does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"The shipment label is not ready.","data":null,"requestId":"","errorCode":"LABEL_NOT_READY","errors":null}}}},"429":{"description":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","data":null,"requestId":"request-id","errorCode":"TOO_MANY_REQUESTS","errors":{"retryAfterSeconds":30}}}}},"500":{"description":"Unexpected error. Contact support with requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Unexpected error. Contact support with requestId.","data":null,"requestId":"request-id","errorCode":"INTERNAL_SERVER_ERROR","errors":null}}}},"503":{"description":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","data":null,"requestId":"request-id","errorCode":"SERVICE_UNAVAILABLE","errors":null}}}}}}},"/shipments":{"get":{"operationId":"shipments.list","summary":"List shipments","description":"Lists shipments with stored prices and package tracking.\n\n## Permission\n\nSHIPMENTS_READ\n\nSee [Troubleshooting](/docs/api/reference/troubleshooting#common-errors) for authentication, access, rate-limit, and service errors.","tags":["shipments"],"parameters":[{"name":"pageSize","in":"query","schema":{"default":20,"type":"integer","minimum":1,"maximum":200},"allowEmptyValue":true,"allowReserved":true,"description":"Maximum records per page: 1–200, default 20. Results are newest first."},{"name":"cursor","in":"query","schema":{"type":"string","minLength":1},"allowEmptyValue":true,"allowReserved":true,"description":"Copy nextCursor from the previous response to fetch the next page. Keep the same filters; omit for the first page."},{"name":"status","in":"query","schema":{"anyOf":[{"enum":["PENDING","PROCESSING","BOOKED","PICKED_UP","DELIVERED","FAILED","CANCELED"],"type":"string"},{"type":"array","items":{"enum":["PENDING","PROCESSING","BOOKED","PICKED_UP","DELIVERED","FAILED","CANCELED"],"type":"string"}}]},"allowEmptyValue":true,"allowReserved":true,"description":"Filter by shipment status. Repeat the status query parameter to include multiple statuses. Omit to include all statuses."},{"name":"customerReference","in":"query","schema":{"type":"string"},"allowEmptyValue":true,"allowReserved":true,"description":"Exact customer-reference match, including an empty string. Omit to disable this filter."},{"name":"createdFrom","in":"query","schema":{"type":"string","format":"date-time","pattern":"T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$"},"allowEmptyValue":true,"allowReserved":true,"description":"Inclusive creation-time lower bound as an RFC 3339 timestamp with seconds and a timezone, for example 2030-01-01T00:00:00+01:00."},{"name":"createdTo","in":"query","schema":{"type":"string","format":"date-time","pattern":"T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$"},"allowEmptyValue":true,"allowReserved":true,"description":"Exclusive creation-time upper bound as an RFC 3339 timestamp with seconds and a timezone. Must not precede createdFrom."}],"responses":{"200":{"description":"Successful result","content":{"application/json":{"example":{"success":true,"message":"Shipments retrieved.","data":{"shipments":[],"nextCursor":null},"requestId":""},"schema":{"type":"object","required":["success","message","data","requestId"],"properties":{"success":{"const":true},"message":{"type":"string"},"data":{"type":"object","properties":{"shipments":{"type":"array","items":{"$ref":"#/components/schemas/Shipment"}},"nextCursor":{"type":["string","null"]}}},"requestId":{"type":"string"}}}}}},"400":{"description":"Invalid input or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Invalid input or unsupported operation.","data":null,"requestId":"request-id","errorCode":"BAD_REQUEST","errors":null}}}},"401":{"description":"Missing or invalid Customer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Missing or invalid Customer API key.","data":null,"requestId":"request-id","errorCode":"UNAUTHORIZED","errors":null}}}},"403":{"description":"Account API access unavailable or required permission missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account API access unavailable or required permission missing.","data":null,"requestId":"request-id","errorCode":"FORBIDDEN","errors":null}}}},"404":{"description":"Resource does not exist or belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Resource does not exist or belongs to another account.","data":null,"requestId":"request-id","errorCode":"NOT_FOUND","errors":null}}}},"429":{"description":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","data":null,"requestId":"request-id","errorCode":"TOO_MANY_REQUESTS","errors":{"retryAfterSeconds":30}}}}},"500":{"description":"Unexpected error. Contact support with requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Unexpected error. Contact support with requestId.","data":null,"requestId":"request-id","errorCode":"INTERNAL_SERVER_ERROR","errors":null}}}},"503":{"description":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","data":null,"requestId":"request-id","errorCode":"SERVICE_UNAVAILABLE","errors":null}}}}}},"post":{"operationId":"shipments.create","summary":"Create shipment draft","description":"Creates a priced shipment draft.\n\n## Prerequisites\n\n- Use a service and package type returned by service discovery for your account.\n- Carrier pickup dates cannot be in the past on the Copenhagen calendar.\n\n## Behavior\n\n- Returns `201` with a `PENDING` draft. Request booking separately.\n- Saves address snapshots and the calculated price.\n- An inline receiver is saved to the address book.\n\n## Permission\n\nSHIPMENTS_WRITE\n\nSee [Troubleshooting](/docs/api/reference/troubleshooting#common-errors) for authentication, access, rate-limit, and service errors.","tags":["shipments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"serviceCode":{"enum":["PALLET","LEMAN_PALLET","BUSINESS_PARCEL","PRIVATE_PARCEL","PICKUP_SHIPMENT","SHOP_DELIVERY","DIRECT_SHOP","SHOP_RETURN","PICKUP_RETURN","GLOBAL_EXPRESS","EXPRESS_10","EXPRESS_12","OTHER"],"type":"string","description":"Choose a serviceCode returned by GET /services for this account. The enum lists recognized codes; availability depends on the account and route. OTHER has no carrier booking or printable label. Express services require pickup and delivery within Denmark."},"senderId":{"type":"string","minLength":1,"description":"Required ID of a saved sender belonging to this account. Obtain it from GET /senders or POST /senders."},"receiverId":{"type":"string","minLength":1,"description":"ID of a saved receiver belonging to this account. Provide exactly one of receiverId or receiver."},"receiver":{"$ref":"#/components/schemas/Address","description":"Inline receiver address instead of receiverId. Creating or replacing a draft saves it in the address book; price preview does not save it."},"pickupDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Valid YYYY-MM-DD date on the Copenhagen calendar. Carrier shipments cannot use a past date; OTHER still requires a valid date."},"packages":{"default":[],"type":"array","items":{"type":"object","properties":{"type":{"enum":["EURO_PALLET_QUARTER","EURO_PALLET_HALF","EURO_PALLET","PKK","LEMAN_EURO_PALLET_HALF","LEMAN_EURO_PALLET","INDUSTRIAL_PALLET","BUSINESS_PARCEL","PRIVATE_PARCEL","PICKUP_SHIPMENT","SHOP_DELIVERY","DIRECT_SHOP","SHOP_RETURN","PICKUP_RETURN","GLOBAL_EXPRESS","EXPRESS_10","EXPRESS_12","OTHER"],"type":"string","description":"Choose a packageTypes[].type returned by GET /services for the selected serviceCode. A recognized enum value is not necessarily enabled for this account."},"weight":{"type":"number","description":"Positive weight of this package in kg, no greater than the selected package type's maxWeight from GET /services.","exclusiveMinimum":0},"length":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}],"description":"Positive package length in cm, no greater than maxLength from GET /services. Required with width and height for international volume-weight pricing; otherwise may be omitted or null."},"width":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}],"description":"Positive package width in cm, no greater than maxWidth from GET /services. Required with length and height for international volume-weight pricing; otherwise may be omitted or null."},"height":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}],"description":"Positive package height in cm, no greater than maxHeight from GET /services. Required when listed in requiredPackageFields or for international volume-weight pricing; otherwise may be omitted or null."},"description":{"type":"string","description":"Package contents or goods description. Required when GET /services lists description in requiredPackageFields. Must not exceed the service's maxDescriptionLength."},"hasDg":{"type":"boolean","description":"Required boolean. Set true for dangerous goods and supply dg. Only GLS and LEMAN services support dangerous goods. Set false for ordinary goods and omit dg or send null."},"dg":{"default":null,"anyOf":[{"type":"object","properties":{"hazardClass":{"type":"string","minLength":1,"description":"Nonempty dangerous-goods hazard-class designation for the shipment."},"unNumber":{"type":"string","minLength":1,"pattern":"^\\d{4}$","description":"Four-digit UN number as a string without the UN prefix, such as 1234. Leading zeros are preserved."},"properShippingName":{"type":"string","minLength":1,"description":"Nonempty proper shipping name of the dangerous goods."},"weight":{"type":"number","description":"Positive weight of the dangerous goods in kg.","exclusiveMinimum":0},"packingGroup":{"type":"string","minLength":1,"description":"Nonempty packing-group designation as text, such as II, appropriate for the goods and carrier."},"flashPoint":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional flash-point value as text. Omit or send null when not needed."},"technicalName":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional technical or chemical name. Omit or send null when not needed."},"marinePollutant":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional marine-pollutant designation as text. Omit or send null when not needed."}},"required":["hazardClass","unNumber","properShippingName","weight","packingGroup"],"additionalProperties":false},{"type":"null"}],"description":"Dangerous-goods details, required when hasDg is true. Must be omitted or null when hasDg is false."}},"required":["type","weight","hasDg"],"additionalProperties":false},"description":"One item per physical package or pallet. At least one is required for carrier services. OTHER accepts an omitted or empty array. Each item requires type, positive weight, and hasDg."},"pickupLocation":{"anyOf":[{"type":"object","properties":{"externalLocationId":{"type":"string","minLength":1,"description":"Carrier's ID for the selected parcel shop, not a Bookogsend address-book ID."}},"required":["externalLocationId"],"additionalProperties":false},{"type":"null"}],"description":"Selected GLS parcel-shop ID. Required for SHOP_DELIVERY. Optional for other carrier services; ignored for OTHER. Bookogsend resolves the shop details and checks that the shop exists in the receiver country."},"isExchangePallets":{"type":"boolean","description":"Enable pallet exchange for serviceCode PALLET only; otherwise ignored. Defaults to false when omitted. If all exchange-count fields are omitted, eligible quarter, half, and full euro pallets are counted from packages."},"exchangePalletsQuarter":{"type":"integer","minimum":0,"maximum":99,"description":"Optional quarter-euro-pallet exchange count, integer 0–99, used with PALLET and isExchangePallets=true. Supplying any exchange count overrides automatic counting; omitted sizes count as zero."},"exchangePalletsHalf":{"type":"integer","minimum":0,"maximum":99,"description":"Optional half-euro-pallet exchange count, integer 0–99, used with PALLET and isExchangePallets=true. Supplying any exchange count overrides automatic counting; omitted sizes count as zero."},"exchangePalletsFull":{"type":"integer","minimum":0,"maximum":99,"description":"Optional full-euro-pallet exchange count, integer 0–99, used with PALLET and isExchangePallets=true. Supplying any exchange count overrides automatic counting; omitted sizes count as zero."},"deliveryNote":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional delivery instructions as text. Omit or send null to clear the value when replacing a draft."},"customerReference":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional reference from your system, such as an order number. Omit or send null to clear the value when replacing a draft. Listing filters match this value exactly."}},"required":["serviceCode","senderId","pickupDate"],"additionalProperties":false},"example":{"serviceCode":"BUSINESS_PARCEL","senderId":"","receiverId":"","pickupDate":"2030-01-15","packages":[{"type":"BUSINESS_PARCEL","weight":1,"length":30,"width":20,"height":10,"hasDg":false}]}}},"description":"Shipment details for a new unbooked PENDING draft. Creating the draft does not request carrier booking."},"responses":{"201":{"description":"Successful result","content":{"application/json":{"example":{"success":true,"message":"Shipment created.","data":{"id":"","status":"PENDING","price":{"currency":"DKK","baseAmount":"100.00","surchargeAmount":"0.00","palletExchangeAmount":"0.00","taxAmount":"25.00","totalAmount":"125.00"},"customerReference":null,"receiverId":""},"requestId":""},"schema":{"type":"object","required":["success","message","data","requestId"],"properties":{"success":{"const":true},"message":{"type":"string"},"data":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string"},"status":{"type":"string"},"price":{"$ref":"#/components/schemas/Price"},"customerReference":{"type":["string","null"]},"receiverId":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"400":{"description":"Invalid shipment input, including an invalid GLS shop ID or receiver-country mismatch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation":{"value":{"success":false,"message":"Invalid input or unsupported operation.","data":null,"requestId":"request-id","errorCode":"BAD_REQUEST","errors":null}},"invalidPickupLocation":{"value":{"success":false,"message":"Select a valid GLS pickup location in the receiver country.","data":null,"requestId":"","errorCode":"INVALID_PICKUP_LOCATION","errors":{"fields":[{"path":"pickupLocation.externalLocationId","errorCode":"INVALID_PICKUP_LOCATION","message":"Select a valid GLS pickup location in the receiver country."}]}}}}}}},"401":{"description":"Missing or invalid Customer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Missing or invalid Customer API key.","data":null,"requestId":"request-id","errorCode":"UNAUTHORIZED","errors":null}}}},"403":{"description":"Account API access unavailable or required permission missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account API access unavailable or required permission missing.","data":null,"requestId":"request-id","errorCode":"FORBIDDEN","errors":null}}}},"404":{"description":"Resource does not exist or belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Resource does not exist or belongs to another account.","data":null,"requestId":"request-id","errorCode":"NOT_FOUND","errors":null}}}},"409":{"description":"State, idempotency, price, or label conflict; inspect errorCode and errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"State, idempotency, price, or label conflict; inspect errorCode and errors.","data":null,"requestId":"request-id","errorCode":"IDEMPOTENCY_KEY_REUSED","errors":null}}}},"429":{"description":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","data":null,"requestId":"request-id","errorCode":"TOO_MANY_REQUESTS","errors":{"retryAfterSeconds":30}}}}},"500":{"description":"Unexpected error. Contact support with requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Unexpected error. Contact support with requestId.","data":null,"requestId":"request-id","errorCode":"INTERNAL_SERVER_ERROR","errors":null}}}},"503":{"description":"Pickup locations or receiver coordinates are temporarily unavailable. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Pickup locations are temporarily unavailable. Try again later.","data":null,"requestId":"","errorCode":"PICKUP_LOCATIONS_UNAVAILABLE","errors":null}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Unique operation key, at most 255 characters after trimming. Retry the same request with the same key; use a new key for a changed request.","example":""}]}},"/shipments/{id}":{"get":{"operationId":"shipments.get","summary":"Get shipment details","description":"Retrieves shipment status, stored details, package tracking, and label readiness.\n\n## Behavior\n\n- Reads do not reprice the shipment. Saved-address updates do not change its snapshots.\n- A `FAILED` shipment includes a failure code and message.\n- Read this endpoint after booking to observe background progress.\n\n## Permission\n\nSHIPMENTS_READ\n\nSee [Troubleshooting](/docs/api/reference/troubleshooting#common-errors) for authentication, access, rate-limit, and service errors.","tags":["shipments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"ID of the shipment. Obtain it from a list or create response. Unavailable IDs return 404.","example":""}],"responses":{"200":{"description":"Successful result","content":{"application/json":{"example":{"success":true,"message":"Shipment retrieved.","data":{"id":"","status":"PENDING","serviceCode":"BUSINESS_PARCEL","createdAt":"2030-01-01T10:00:00.000Z","pickupDate":"2030-01-15","customerReference":null,"deliveryNote":null,"sender":{"name":"Example Company","street1":"Østerbrogade 1","city":"København Ø","zip":"2100","country":"DK","addressType":"COMMERCIAL","street2":null,"region":null,"attention":null,"email":null,"phone":null,"mobile":null},"receiver":{"name":"Example Company","street1":"Østerbrogade 1","city":"København Ø","zip":"2100","country":"DK","addressType":"COMMERCIAL","street2":null,"region":null,"attention":null,"email":null,"phone":null,"mobile":null},"price":{"currency":"DKK","baseAmount":"100.00","surchargeAmount":"0.00","palletExchangeAmount":"0.00","taxAmount":"25.00","totalAmount":"125.00"},"packages":[{"type":"BUSINESS_PARCEL","weight":1,"length":30,"width":20,"height":10,"hasDg":false,"id":"","description":null,"dg":null,"trackingNumber":null,"nationalTrackingNumber":null,"deliveryStatus":"PENDING"}],"labelReady":false,"failure":null},"requestId":""},"schema":{"type":"object","required":["success","message","data","requestId"],"properties":{"success":{"const":true},"message":{"type":"string"},"data":{"allOf":[{"$ref":"#/components/schemas/Shipment"},{"type":"object","properties":{"sender":{"$ref":"#/components/schemas/Address"},"receiver":{"$ref":"#/components/schemas/Address"},"deliveryNote":{"type":["string","null"]},"packages":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentPackage"}},"failure":{"type":["object","null"],"properties":{"code":{"enum":["INVALID_ZIPCODE","INVALID_SHIPMENT_DATE","UNKNOWN_PROVIDER_ERROR"]},"message":{"type":"string"}}}}}]},"requestId":{"type":"string"}}}}}},"400":{"description":"Invalid input or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Invalid input or unsupported operation.","data":null,"requestId":"request-id","errorCode":"BAD_REQUEST","errors":null}}}},"401":{"description":"Missing or invalid Customer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Missing or invalid Customer API key.","data":null,"requestId":"request-id","errorCode":"UNAUTHORIZED","errors":null}}}},"403":{"description":"Account API access unavailable or required permission missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account API access unavailable or required permission missing.","data":null,"requestId":"request-id","errorCode":"FORBIDDEN","errors":null}}}},"404":{"description":"Resource does not exist or belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Resource does not exist or belongs to another account.","data":null,"requestId":"request-id","errorCode":"NOT_FOUND","errors":null}}}},"429":{"description":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","data":null,"requestId":"request-id","errorCode":"TOO_MANY_REQUESTS","errors":{"retryAfterSeconds":30}}}}},"500":{"description":"Unexpected error. Contact support with requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Unexpected error. Contact support with requestId.","data":null,"requestId":"request-id","errorCode":"INTERNAL_SERVER_ERROR","errors":null}}}},"503":{"description":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","data":null,"requestId":"request-id","errorCode":"SERVICE_UNAVAILABLE","errors":null}}}}}},"put":{"operationId":"shipments.update","summary":"Update shipment draft","description":"Updates and reprices a shipment draft.\n\n## Prerequisites\n\n- The shipment must be `PENDING`.\n- It must have no linked payments, quotations, proforma data, or automatic returns.\n- The updated shipment must meet the current service and pickup-date requirements.\n\n## Behavior\n\n- Updates the address snapshots and packages and recalculates the price.\n- Omitted `customerReference` and `deliveryNote` values are cleared.\n- An inline receiver is saved to the address book.\n- The draft stays `PENDING`; updating does not request booking.\n- `409 CONFLICT` includes `errors.currentStatus` when the shipment status blocks the update.\n\n## Permission\n\nSHIPMENTS_WRITE\n\nSee [Troubleshooting](/docs/api/reference/troubleshooting#common-errors) for authentication, access, rate-limit, and service errors.","tags":["shipments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"ID of the shipment. Obtain it from a list or create response. Unavailable IDs return 404.","example":""},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Unique operation key, at most 255 characters after trimming. Retry the same request with the same key; use a new key for a changed request.","example":""}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"serviceCode":{"enum":["PALLET","LEMAN_PALLET","BUSINESS_PARCEL","PRIVATE_PARCEL","PICKUP_SHIPMENT","SHOP_DELIVERY","DIRECT_SHOP","SHOP_RETURN","PICKUP_RETURN","GLOBAL_EXPRESS","EXPRESS_10","EXPRESS_12","OTHER"],"type":"string","description":"Choose a serviceCode returned by GET /services for this account. The enum lists recognized codes; availability depends on the account and route. OTHER has no carrier booking or printable label. Express services require pickup and delivery within Denmark."},"senderId":{"type":"string","minLength":1,"description":"Required ID of a saved sender belonging to this account. Obtain it from GET /senders or POST /senders."},"receiverId":{"type":"string","minLength":1,"description":"ID of a saved receiver belonging to this account. Provide exactly one of receiverId or receiver."},"receiver":{"$ref":"#/components/schemas/Address","description":"Inline receiver address instead of receiverId. Creating or replacing a draft saves it in the address book; price preview does not save it."},"pickupDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Valid YYYY-MM-DD date on the Copenhagen calendar. Carrier shipments cannot use a past date; OTHER still requires a valid date."},"packages":{"default":[],"type":"array","items":{"type":"object","properties":{"type":{"enum":["EURO_PALLET_QUARTER","EURO_PALLET_HALF","EURO_PALLET","PKK","LEMAN_EURO_PALLET_HALF","LEMAN_EURO_PALLET","INDUSTRIAL_PALLET","BUSINESS_PARCEL","PRIVATE_PARCEL","PICKUP_SHIPMENT","SHOP_DELIVERY","DIRECT_SHOP","SHOP_RETURN","PICKUP_RETURN","GLOBAL_EXPRESS","EXPRESS_10","EXPRESS_12","OTHER"],"type":"string","description":"Choose a packageTypes[].type returned by GET /services for the selected serviceCode. A recognized enum value is not necessarily enabled for this account."},"weight":{"type":"number","description":"Positive weight of this package in kg, no greater than the selected package type's maxWeight from GET /services.","exclusiveMinimum":0},"length":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}],"description":"Positive package length in cm, no greater than maxLength from GET /services. Required with width and height for international volume-weight pricing; otherwise may be omitted or null."},"width":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}],"description":"Positive package width in cm, no greater than maxWidth from GET /services. Required with length and height for international volume-weight pricing; otherwise may be omitted or null."},"height":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}],"description":"Positive package height in cm, no greater than maxHeight from GET /services. Required when listed in requiredPackageFields or for international volume-weight pricing; otherwise may be omitted or null."},"description":{"type":"string","description":"Package contents or goods description. Required when GET /services lists description in requiredPackageFields. Must not exceed the service's maxDescriptionLength."},"hasDg":{"type":"boolean","description":"Required boolean. Set true for dangerous goods and supply dg. Only GLS and LEMAN services support dangerous goods. Set false for ordinary goods and omit dg or send null."},"dg":{"default":null,"anyOf":[{"type":"object","properties":{"hazardClass":{"type":"string","minLength":1,"description":"Nonempty dangerous-goods hazard-class designation for the shipment."},"unNumber":{"type":"string","minLength":1,"pattern":"^\\d{4}$","description":"Four-digit UN number as a string without the UN prefix, such as 1234. Leading zeros are preserved."},"properShippingName":{"type":"string","minLength":1,"description":"Nonempty proper shipping name of the dangerous goods."},"weight":{"type":"number","description":"Positive weight of the dangerous goods in kg.","exclusiveMinimum":0},"packingGroup":{"type":"string","minLength":1,"description":"Nonempty packing-group designation as text, such as II, appropriate for the goods and carrier."},"flashPoint":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional flash-point value as text. Omit or send null when not needed."},"technicalName":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional technical or chemical name. Omit or send null when not needed."},"marinePollutant":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional marine-pollutant designation as text. Omit or send null when not needed."}},"required":["hazardClass","unNumber","properShippingName","weight","packingGroup"],"additionalProperties":false},{"type":"null"}],"description":"Dangerous-goods details, required when hasDg is true. Must be omitted or null when hasDg is false."}},"required":["type","weight","hasDg"],"additionalProperties":false},"description":"One item per physical package or pallet. At least one is required for carrier services. OTHER accepts an omitted or empty array. Each item requires type, positive weight, and hasDg."},"pickupLocation":{"anyOf":[{"type":"object","properties":{"externalLocationId":{"type":"string","minLength":1,"description":"Carrier's ID for the selected parcel shop, not a Bookogsend address-book ID."}},"required":["externalLocationId"],"additionalProperties":false},{"type":"null"}],"description":"Selected GLS parcel-shop ID. Required for SHOP_DELIVERY. Optional for other carrier services; ignored for OTHER. Bookogsend resolves the shop details and checks that the shop exists in the receiver country."},"isExchangePallets":{"type":"boolean","description":"Enable pallet exchange for serviceCode PALLET only; otherwise ignored. Defaults to false when omitted. If all exchange-count fields are omitted, eligible quarter, half, and full euro pallets are counted from packages."},"exchangePalletsQuarter":{"type":"integer","minimum":0,"maximum":99,"description":"Optional quarter-euro-pallet exchange count, integer 0–99, used with PALLET and isExchangePallets=true. Supplying any exchange count overrides automatic counting; omitted sizes count as zero."},"exchangePalletsHalf":{"type":"integer","minimum":0,"maximum":99,"description":"Optional half-euro-pallet exchange count, integer 0–99, used with PALLET and isExchangePallets=true. Supplying any exchange count overrides automatic counting; omitted sizes count as zero."},"exchangePalletsFull":{"type":"integer","minimum":0,"maximum":99,"description":"Optional full-euro-pallet exchange count, integer 0–99, used with PALLET and isExchangePallets=true. Supplying any exchange count overrides automatic counting; omitted sizes count as zero."},"deliveryNote":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional delivery instructions as text. Omit or send null to clear the value when replacing a draft."},"customerReference":{"default":null,"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional reference from your system, such as an order number. Omit or send null to clear the value when replacing a draft. Listing filters match this value exactly."}},"required":["serviceCode","senderId","pickupDate"],"additionalProperties":false},"example":{"serviceCode":"BUSINESS_PARCEL","senderId":"","receiverId":"","pickupDate":"2030-01-15","packages":[{"type":"BUSINESS_PARCEL","weight":1,"length":30,"width":20,"height":10,"hasDg":false}]}}},"description":"Updated shipment details. Required fields are shown in the schema."},"responses":{"200":{"description":"Successful result","content":{"application/json":{"example":{"success":true,"message":"Shipment updated.","data":{"id":"","status":"PENDING","price":{"currency":"DKK","baseAmount":"100.00","surchargeAmount":"0.00","palletExchangeAmount":"0.00","taxAmount":"25.00","totalAmount":"125.00"},"customerReference":null,"receiverId":""},"requestId":""},"schema":{"type":"object","required":["success","message","data","requestId"],"properties":{"success":{"const":true},"message":{"type":"string"},"data":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string"},"status":{"type":"string"},"price":{"$ref":"#/components/schemas/Price"},"customerReference":{"type":["string","null"]},"receiverId":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"400":{"description":"Invalid shipment input, including an invalid GLS shop ID or receiver-country mismatch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation":{"value":{"success":false,"message":"Invalid input or unsupported operation.","data":null,"requestId":"request-id","errorCode":"BAD_REQUEST","errors":null}},"invalidPickupLocation":{"value":{"success":false,"message":"Select a valid GLS pickup location in the receiver country.","data":null,"requestId":"","errorCode":"INVALID_PICKUP_LOCATION","errors":{"fields":[{"path":"pickupLocation.externalLocationId","errorCode":"INVALID_PICKUP_LOCATION","message":"Select a valid GLS pickup location in the receiver country."}]}}}}}}},"401":{"description":"Missing or invalid Customer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Missing or invalid Customer API key.","data":null,"requestId":"request-id","errorCode":"UNAUTHORIZED","errors":null}}}},"403":{"description":"Account API access unavailable or required permission missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account API access unavailable or required permission missing.","data":null,"requestId":"request-id","errorCode":"FORBIDDEN","errors":null}}}},"404":{"description":"Resource does not exist or belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Resource does not exist or belongs to another account.","data":null,"requestId":"request-id","errorCode":"NOT_FOUND","errors":null}}}},"409":{"description":"State, idempotency, price, or label conflict; inspect errorCode and errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"State, idempotency, price, or label conflict; inspect errorCode and errors.","data":null,"requestId":"request-id","errorCode":"IDEMPOTENCY_KEY_REUSED","errors":null}}}},"429":{"description":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","data":null,"requestId":"request-id","errorCode":"TOO_MANY_REQUESTS","errors":{"retryAfterSeconds":30}}}}},"500":{"description":"Unexpected error. Contact support with requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Unexpected error. Contact support with requestId.","data":null,"requestId":"request-id","errorCode":"INTERNAL_SERVER_ERROR","errors":null}}}},"503":{"description":"Pickup locations or receiver coordinates are temporarily unavailable. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Pickup locations are temporarily unavailable. Try again later.","data":null,"requestId":"","errorCode":"PICKUP_LOCATIONS_UNAVAILABLE","errors":null}}}}}}},"/shipments/{id}/book":{"post":{"operationId":"shipments.book","summary":"Book shipment","description":"Submits a shipment draft for carrier booking.\n\n## Prerequisites\n\n- The shipment must be `PENDING`.\n- It must have no linked payments, quotations, proforma data, or automatic returns.\n- The service must support carrier booking. `OTHER` cannot be booked.\n- The stored shipment must meet current service requirements and have an available price greater than zero.\n\n## Behavior\n\n- Booking revalidates the draft and recalculates its price. For parcel-shop delivery, it also revalidates the stored shop ID and refreshes the shop details.\n- `200` with `PROCESSING` confirms queue dispatch. Read the shipment for the completed booking result.\n- `409 PRICE_CHANGED` keeps the draft `PENDING`, updates its price, and returns `errors.price`. Review the price and use a new idempotency key to accept it. The previous key replays the conflict.\n- `409 SERVICE_NO_LONGER_AVAILABLE` queues no booking.\n- Retry a `503` dispatch failure with the same idempotency key.\n\n## Permission\n\nSHIPMENTS_WRITE\n\nSee [Troubleshooting](/docs/api/reference/troubleshooting#common-errors) for authentication, access, rate-limit, and service errors.","tags":["shipments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"ID of the shipment. Obtain it from a list or create response. Unavailable IDs return 404.","example":""},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Unique operation key, at most 255 characters after trimming. Retry the same request with the same key; use a new key for a changed request.","example":""}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"default":{},"type":"object","additionalProperties":false},"example":{}}},"description":"Empty JSON object ({}). No payload fields are accepted. The shipment ID comes from the URL."},"responses":{"200":{"description":"Successful result","content":{"application/json":{"example":{"success":true,"message":"Shipment queued for booking.","data":{"id":"","status":"PROCESSING","price":{"currency":"DKK","baseAmount":"100.00","surchargeAmount":"0.00","palletExchangeAmount":"0.00","taxAmount":"25.00","totalAmount":"125.00"},"customerReference":null},"requestId":""},"schema":{"type":"object","required":["success","message","data","requestId"],"properties":{"success":{"const":true},"message":{"type":"string"},"data":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string"},"status":{"type":"string"},"price":{"$ref":"#/components/schemas/Price"},"customerReference":{"type":["string","null"]}}},"requestId":{"type":"string"}}}}}},"400":{"description":"Invalid shipment input, including an invalid GLS shop ID or receiver-country mismatch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation":{"value":{"success":false,"message":"Invalid input or unsupported operation.","data":null,"requestId":"request-id","errorCode":"BAD_REQUEST","errors":null}},"invalidPickupLocation":{"value":{"success":false,"message":"Select a valid GLS pickup location in the receiver country.","data":null,"requestId":"","errorCode":"INVALID_PICKUP_LOCATION","errors":{"fields":[{"path":"pickupLocation.externalLocationId","errorCode":"INVALID_PICKUP_LOCATION","message":"Select a valid GLS pickup location in the receiver country."}]}}}}}}},"401":{"description":"Missing or invalid Customer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Missing or invalid Customer API key.","data":null,"requestId":"request-id","errorCode":"UNAUTHORIZED","errors":null}}}},"403":{"description":"Account API access unavailable or required permission missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account API access unavailable or required permission missing.","data":null,"requestId":"request-id","errorCode":"FORBIDDEN","errors":null}}}},"404":{"description":"Resource does not exist or belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Resource does not exist or belongs to another account.","data":null,"requestId":"request-id","errorCode":"NOT_FOUND","errors":null}}}},"409":{"description":"State, idempotency, price, or label conflict; inspect errorCode and errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"State, idempotency, price, or label conflict; inspect errorCode and errors.","data":null,"requestId":"request-id","errorCode":"IDEMPOTENCY_KEY_REUSED","errors":null}}}},"429":{"description":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","data":null,"requestId":"request-id","errorCode":"TOO_MANY_REQUESTS","errors":{"retryAfterSeconds":30}}}}},"500":{"description":"Unexpected error. Contact support with requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Unexpected error. Contact support with requestId.","data":null,"requestId":"request-id","errorCode":"INTERNAL_SERVER_ERROR","errors":null}}}},"503":{"description":"Shop lookup or booking dispatch is temporarily unavailable. Retry booking with the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pickupLocationsUnavailable":{"value":{"success":false,"message":"Pickup locations are temporarily unavailable. Try again later.","data":null,"requestId":"","errorCode":"PICKUP_LOCATIONS_UNAVAILABLE","errors":null}},"dispatchUnavailable":{"value":{"success":false,"message":"Booking could not be queued. Retry with the same Idempotency-Key.","data":null,"requestId":"","errorCode":"SERVICE_UNAVAILABLE","errors":null}}}}}}}}},"/shipments/{id}/cancel":{"post":{"operationId":"shipments.cancel","summary":"Cancel shipment","description":"Cancels a shipment before pickup.\n\n## Prerequisites\n\n- For a new cancellation, the shipment must be `PENDING` or `BOOKED`.\n- No package may have progressed beyond its pending delivery state.\n- Any connected return must be `PENDING`, `BOOKED`, or `FAILED`, with no package beyond its pending delivery state.\n\n## Behavior\n\n- Successful cancellation changes the status to `CANCELED` and retains the shipment record.\n- Canceling an already canceled shipment succeeds without changing its status.\n- `409 CANCELLATION_NOT_ALLOWED` includes `errors.currentStatus`.\n- Success confirms committed cancellation. Notifications and fulfillment reconciliation run afterward in the background.\n\n## Permission\n\nSHIPMENTS_WRITE\n\nSee [Troubleshooting](/docs/api/reference/troubleshooting#common-errors) for authentication, access, rate-limit, and service errors.","tags":["shipments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1},"description":"ID of the shipment. Obtain it from a list or create response. Unavailable IDs return 404.","example":""},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Unique operation key, at most 255 characters after trimming. Retry the same request with the same key; use a new key for a changed request.","example":""}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"default":{},"type":"object","additionalProperties":false},"example":{}}},"description":"Empty JSON object ({}). No payload fields are accepted. The shipment ID comes from the URL."},"responses":{"200":{"description":"Successful result","content":{"application/json":{"example":{"success":true,"message":"Shipment canceled.","data":{"id":"","status":"CANCELED"},"requestId":""},"schema":{"type":"object","required":["success","message","data","requestId"],"properties":{"success":{"const":true},"message":{"type":"string"},"data":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string"},"status":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"400":{"description":"Invalid input or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Invalid input or unsupported operation.","data":null,"requestId":"request-id","errorCode":"BAD_REQUEST","errors":null}}}},"401":{"description":"Missing or invalid Customer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Missing or invalid Customer API key.","data":null,"requestId":"request-id","errorCode":"UNAUTHORIZED","errors":null}}}},"403":{"description":"Account API access unavailable or required permission missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account API access unavailable or required permission missing.","data":null,"requestId":"request-id","errorCode":"FORBIDDEN","errors":null}}}},"404":{"description":"Resource does not exist or belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Resource does not exist or belongs to another account.","data":null,"requestId":"request-id","errorCode":"NOT_FOUND","errors":null}}}},"409":{"description":"State, idempotency, price, or label conflict; inspect errorCode and errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"State, idempotency, price, or label conflict; inspect errorCode and errors.","data":null,"requestId":"request-id","errorCode":"IDEMPOTENCY_KEY_REUSED","errors":null}}}},"429":{"description":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Account limit exceeded: 120 requests per minute shared by all account keys. Wait errors.retryAfterSeconds seconds before retrying.","data":null,"requestId":"request-id","errorCode":"TOO_MANY_REQUESTS","errors":{"retryAfterSeconds":30}}}}},"500":{"description":"Unexpected error. Contact support with requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Unexpected error. Contact support with requestId.","data":null,"requestId":"request-id","errorCode":"INTERNAL_SERVER_ERROR","errors":null}}}},"503":{"description":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"message":"Temporary service or dispatch failure. Retry mutations with the same idempotency key.","data":null,"requestId":"request-id","errorCode":"SERVICE_UNAVAILABLE","errors":null}}}}}}}},"tags":[{"name":"services","description":"Available services, supported package types, and account-specific limits."},{"name":"prices","description":"Price previews without creating or booking a shipment."},{"name":"senders","description":"Saved sender addresses."},{"name":"receivers","description":"Saved receiver addresses."},{"name":"pickup-locations","description":"GLS parcel shops near a receiver address."},{"name":"shipments","description":"Drafts, booking, status, tracking, cancellation, and existing labels."}]}