{"items":[{"type":"link","label":"UPS 4th Party API Integration","link":"/zh-hans/v1/ps_openapi","routeSlug":"/zh-hans/v1/ps_openapi","content":{"contentType":"overview","meta":{"name":"UPS 4th Party API Integration"},"children":[{"nodeType":"container","panels":[{"title":"Overview","titleTranslationKey":"info.title","children":[{"kind":"externallink","title":"License","titleTranslationKey":"info.license","label":"Apache 2.0","url":"https://www.apache.org/licenses/LICENSE-2.0"}]},{"title":"Languages","titleTranslationKey":"languages.title","children":[{"kind":"languages","options":[{"key":"curl","title":"curl","lang":"curl"},{"key":"javascript","title":"JavaScript","lang":"JavaScript"},{"key":"node","title":"Node.js","lang":"Node.js"},{"key":"python","title":"Python","lang":"Python"},{"key":"java","title":"Java","lang":"Java"},{"key":"csharp","title":"C#","lang":"C#"},{"key":"php","title":"PHP","lang":"PHP"},{"key":"go","title":"Go","lang":"Go"},{"key":"ruby","title":"Ruby","lang":"Ruby"},{"key":"r","title":"R","lang":"R"},{"key":"payload","title":"Payload","lang":"Payload"}]}]},{"title":"Servers","titleTranslationKey":"servers.title","children":[{"kind":"servers","servers":[{"url":"https://ps-api.shipsaving.com","description":"Production server"},{"url":"https://ps-api.shipsaving.us","description":"Sandbox server"}],"mode":"default"}]}],"children":[{"nodeType":"overview-section-wrapper","children":[{"nodeType":"header","level":1,"label":"UPS 4th Party API Integration (v1)","showPageActions":true},{"nodeType":"overview-section-wrapper","children":[{"nodeType":"markdoc","content":"This document outlines the integration of ShipSaving APIs under the UPS 4th party account model, including account creation, label generation, and other workflows."}],"sectionId":"/zh-hans/v1/ps_openapi"}],"sectionId":"/zh-hans/v1/ps_openapi"}]}]}},{"type":"group","label":"Label Management","link":"/zh-hans/v1/ps_openapi/label-management","routeSlug":"/zh-hans/v1/ps_openapi/label-management","items":[{"label":"Get Rates","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v1/ps_openapi/label-management/getratelist","routeSlug":"/zh-hans/v1/ps_openapi/label-management/getratelist","metadata":{"seo":{"title":"Get Rates","description":"Retrieve available shipping rates for the given package dimensions, weight, and origin/destination addresses. Returns rates across all active carrier accounts, sorted by price."}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"getRateList","name":"Get Rates","isWebhook":false,"pointer":"/paths/~1api~1rates~1list/post","hasSamples":true},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Get Rates","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":"Retrieve available shipping rates for the given package dimensions, weight, and origin/destination addresses. Returns rates across all active carrier accounts, sorted by price.\n"},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Pass the API token as a Bearer token in the "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Authorization"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" header. Example: "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Authorization: Bearer <api_token>"},"children":[]}]}]}]}]},{"schemes":[{"name":"ApiTokenAuth","scopes":[],"type":"apiKey","in":"query","paramName":"api_token","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Pass the API token as a query parameter. Example: "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"?api_token=<api_token>"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"body","label":"Request Body","labelTranslationKey":"body","required":true,"mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/RateListRequest"}},"schemaId":"components/schemas/RateListRequest","pointer":"/paths/~1api~1rates~1list/post/requestBody"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"POST","path":"/api/rates/list","servers":[{"url":"https://ps-api.shipsaving.com","description":"Production server"},{"url":"https://ps-api.shipsaving.us","description":"Sandbox server"}],"parameters":{"path":[],"query":[],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer"}],"scopes":[]},{"schemes":[{"id":"ApiTokenAuth","type":"apiKey","name":"api_token","in":"query"}],"scopes":[]}],"requestBody":{"application/json":{"schemaId":"components/schemas/RateListRequest"}},"responseCodes":["200","400"],"pointer":"/api/rates/list","href":"label-management/getratelist","openApiOperationId":"getRateList","summary":"Get Rates","securityGroups":[{"BearerAuth":[]},{"ApiTokenAuth":[]}]},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://ps-api.shipsaving.com","description":"Production server"},{"url":"https://ps-api.shipsaving.us","description":"Sandbox server"}],"schemaId":"components/schemas/RateListRequest","mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/RateListRequest"}},"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":"Rates retrieved successfully","mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"schema_221"}},"schemaId":"schema_221"},{"code":"400","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bad request — validation error or business rule violation"},"children":[]}]}]}],"mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1rates~1list/post/responses/400/content/application~1json/example"]}},"schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1rates~1list/post/responses/400/content/application~1json/example"]}],"pointer":"/paths/~1api~1rates~1list/post/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"schema_221","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"schema_221"}}},{"code":"400","schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1rates~1list/post/responses/400/content/application~1json/example"],"mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1rates~1list/post/responses/400/content/application~1json/example"]}}}],"examples":[]}]}]}]},"httpPath":"/api/rates/list"},{"label":"Buy Label","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v1/ps_openapi/label-management/buylabel","routeSlug":"/zh-hans/v1/ps_openapi/label-management/buylabel","metadata":{"seo":{"title":"Buy Label","description":"Purchase a shipping label using the rate_id returned by Get Rates."}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"buyLabel","name":"Buy Label","isWebhook":false,"pointer":"/paths/~1api~1rates~1buy/get","hasSamples":false},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Buy Label","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Purchase a shipping label using the "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"rate_id"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" returned by "},"children":[]},{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Get Rates"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"."},"children":[]}]}]}]},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Pass the API token as a Bearer token in the "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Authorization"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" header. Example: "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Authorization: Bearer <api_token>"},"children":[]}]}]}]}]},{"schemes":[{"name":"ApiTokenAuth","scopes":[],"type":"apiKey","in":"query","paramName":"api_token","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Pass the API token as a query parameter. Example: "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"?api_token=<api_token>"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"query","label":"Query","labelTranslationKey":"query","parameters":[{"name":"rate_id","in":"query","schemaId":"schema_222","description":"Rate identifier returned by the Get Rates endpoint.","required":true,"example":"rate_e50d02e2-047a-402c-aa32-22ad0926db00"}],"pointer":"/paths/~1api~1rates~1buy/get/parameters"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"GET","path":"/api/rates/buy","servers":[{"url":"https://ps-api.shipsaving.com","description":"Production server"},{"url":"https://ps-api.shipsaving.us","description":"Sandbox server"}],"parameters":{"path":[],"query":[{"name":"rate_id","in":"query","required":true,"example":"rate_e50d02e2-047a-402c-aa32-22ad0926db00","schemaId":"schema_222"}],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer"}],"scopes":[]},{"schemes":[{"id":"ApiTokenAuth","type":"apiKey","name":"api_token","in":"query"}],"scopes":[]}],"responseCodes":["200","400","403"],"pointer":"/api/rates/buy","href":"label-management/buylabel","openApiOperationId":"buyLabel","summary":"Buy Label","securityGroups":[{"BearerAuth":[]},{"ApiTokenAuth":[]}]},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://ps-api.shipsaving.com","description":"Production server"},{"url":"https://ps-api.shipsaving.us","description":"Sandbox server"}],"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":"Label purchased successfully","mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"schema_223"}},"schemaId":"schema_223"},{"code":"400","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bad request — validation error or business rule violation"},"children":[]}]}]}],"mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1rates~1buy/get/responses/400/content/application~1json/example"]}},"schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1rates~1buy/get/responses/400/content/application~1json/example"]},{"code":"403","description":"Daily label purchase limit exceeded","mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1rates~1buy/get/responses/403/content/application~1json/example"]}},"schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1rates~1buy/get/responses/403/content/application~1json/example"]}],"pointer":"/paths/~1api~1rates~1buy/get/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"schema_223","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"schema_223"}}},{"code":"400","schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1rates~1buy/get/responses/400/content/application~1json/example"],"mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1rates~1buy/get/responses/400/content/application~1json/example"]}}},{"code":"403","schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1rates~1buy/get/responses/403/content/application~1json/example"],"mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1rates~1buy/get/responses/403/content/application~1json/example"]}}}],"examples":[]}]}]}]},"httpPath":"/api/rates/buy"},{"label":"Void Label","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v1/ps_openapi/label-management/voidlabel","routeSlug":"/zh-hans/v1/ps_openapi/label-management/voidlabel","metadata":{"seo":{"title":"Void Label","description":"Void a previously purchased shipping label by tracking number."}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"voidLabel","name":"Void Label","isWebhook":false,"pointer":"/paths/~1api~1shipments~1void/post","hasSamples":true},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Void Label","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":"Void a previously purchased shipping label by tracking number.\n"},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Pass the API token as a Bearer token in the "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Authorization"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" header. Example: "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Authorization: Bearer <api_token>"},"children":[]}]}]}]}]},{"schemes":[{"name":"ApiTokenAuth","scopes":[],"type":"apiKey","in":"query","paramName":"api_token","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Pass the API token as a query parameter. Example: "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"?api_token=<api_token>"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"body","label":"Request Body","labelTranslationKey":"body","required":true,"mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"schema_224"}},"schemaId":"schema_224","pointer":"/paths/~1api~1shipments~1void/post/requestBody"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"POST","path":"/api/shipments/void","servers":[{"url":"https://ps-api.shipsaving.com","description":"Production server"},{"url":"https://ps-api.shipsaving.us","description":"Sandbox server"}],"parameters":{"path":[],"query":[],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer"}],"scopes":[]},{"schemes":[{"id":"ApiTokenAuth","type":"apiKey","name":"api_token","in":"query"}],"scopes":[]}],"requestBody":{"application/json":{"schemaId":"schema_224"}},"responseCodes":["200","400"],"pointer":"/api/shipments/void","href":"label-management/voidlabel","openApiOperationId":"voidLabel","summary":"Void Label","securityGroups":[{"BearerAuth":[]},{"ApiTokenAuth":[]}]},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://ps-api.shipsaving.com","description":"Production server"},{"url":"https://ps-api.shipsaving.us","description":"Sandbox server"}],"schemaId":"schema_224","mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"schema_224"}},"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":"Label voided successfully","mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"schema_225","exampleIds":["paths/~1api~1shipments~1void/post/responses/200/content/application~1json/example"]}},"schemaId":"schema_225","exampleIds":["paths/~1api~1shipments~1void/post/responses/200/content/application~1json/example"]},{"code":"400","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bad request — validation error or business rule violation"},"children":[]}]}]}],"mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1shipments~1void/post/responses/400/content/application~1json/example"]}},"schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1shipments~1void/post/responses/400/content/application~1json/example"]}],"pointer":"/paths/~1api~1shipments~1void/post/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"schema_225","exampleIds":["paths/~1api~1shipments~1void/post/responses/200/content/application~1json/example"],"mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"schema_225","exampleIds":["paths/~1api~1shipments~1void/post/responses/200/content/application~1json/example"]}}},{"code":"400","schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1shipments~1void/post/responses/400/content/application~1json/example"],"mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1shipments~1void/post/responses/400/content/application~1json/example"]}}}],"examples":[]}]}]}]},"httpPath":"/api/shipments/void"},{"label":"Get Billing & Void Status","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v1/ps_openapi/label-management/getshipmentstatus","routeSlug":"/zh-hans/v1/ps_openapi/label-management/getshipmentstatus","metadata":{"seo":{"title":"Get Billing & Void Status","description":"Retrieve the carrier billing state and void state of a previously purchased label, looked up by tracking number."}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"getShipmentStatus","name":"Get Billing & Void Status","isWebhook":false,"pointer":"/paths/~1api~1shipments~1status/get","hasSamples":false},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Get Billing & Void Status","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":"Retrieve the carrier billing state and void state of a previously purchased label, looked up by tracking number.\n"},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Pass the API token as a Bearer token in the "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Authorization"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" header. Example: "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Authorization: Bearer <api_token>"},"children":[]}]}]}]}]},{"schemes":[{"name":"ApiTokenAuth","scopes":[],"type":"apiKey","in":"query","paramName":"api_token","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Pass the API token as a query parameter. Example: "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"?api_token=<api_token>"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"query","label":"Query","labelTranslationKey":"query","parameters":[{"name":"tracking_code","in":"query","schemaId":"schema_222","description":"Tracking number of the shipment to look up. \n","required":true,"example":"1ZXXXXXXXXXXXXX"}],"pointer":"/paths/~1api~1shipments~1status/get/parameters"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"GET","path":"/api/shipments/status","servers":[{"url":"https://ps-api.shipsaving.com","description":"Production server"},{"url":"https://ps-api.shipsaving.us","description":"Sandbox server"}],"parameters":{"path":[],"query":[{"name":"tracking_code","in":"query","required":true,"example":"1ZXXXXXXXXXXXXX","schemaId":"schema_222"}],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer"}],"scopes":[]},{"schemes":[{"id":"ApiTokenAuth","type":"apiKey","name":"api_token","in":"query"}],"scopes":[]}],"responseCodes":["200","400"],"pointer":"/api/shipments/status","href":"label-management/getshipmentstatus","openApiOperationId":"getShipmentStatus","summary":"Get Billing & Void Status","securityGroups":[{"BearerAuth":[]},{"ApiTokenAuth":[]}]},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://ps-api.shipsaving.com","description":"Production server"},{"url":"https://ps-api.shipsaving.us","description":"Sandbox server"}],"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":"Shipment status retrieved successfully","mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/ShipmentStatusResponse","exampleIds":["paths/~1api~1shipments~1status/get/responses/200/content/application~1json/examples/billingCompleted","paths/~1api~1shipments~1status/get/responses/200/content/application~1json/examples/voidedAndRefunded"]}},"schemaId":"components/schemas/ShipmentStatusResponse","exampleIds":["paths/~1api~1shipments~1status/get/responses/200/content/application~1json/examples/billingCompleted","paths/~1api~1shipments~1status/get/responses/200/content/application~1json/examples/voidedAndRefunded"]},{"code":"400","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bad request — "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"tracking_code"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" was missing or blank, or no shipment with that tracking number exists under the authenticated company."},"children":[]}]}]}],"mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1shipments~1status/get/responses/400/content/application~1json/examples/missingTrackingCode","paths/~1api~1shipments~1status/get/responses/400/content/application~1json/examples/trackingCodeNotFound"]}},"schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1shipments~1status/get/responses/400/content/application~1json/examples/missingTrackingCode","paths/~1api~1shipments~1status/get/responses/400/content/application~1json/examples/trackingCodeNotFound"]}],"pointer":"/paths/~1api~1shipments~1status/get/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"components/schemas/ShipmentStatusResponse","exampleIds":["paths/~1api~1shipments~1status/get/responses/200/content/application~1json/examples/billingCompleted","paths/~1api~1shipments~1status/get/responses/200/content/application~1json/examples/voidedAndRefunded"],"mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/ShipmentStatusResponse","exampleIds":["paths/~1api~1shipments~1status/get/responses/200/content/application~1json/examples/billingCompleted","paths/~1api~1shipments~1status/get/responses/200/content/application~1json/examples/voidedAndRefunded"]}}},{"code":"400","schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1shipments~1status/get/responses/400/content/application~1json/examples/missingTrackingCode","paths/~1api~1shipments~1status/get/responses/400/content/application~1json/examples/trackingCodeNotFound"],"mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1shipments~1status/get/responses/400/content/application~1json/examples/missingTrackingCode","paths/~1api~1shipments~1status/get/responses/400/content/application~1json/examples/trackingCodeNotFound"]}}}],"examples":[]}]}]}]},"httpPath":"/api/shipments/status"}],"content":{"contentType":"group","meta":{"name":"Label Management"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Label Management","showPageActions":true}],"panels":[{"children":[{"kind":"group-items","title":"Operations","titleTranslationKey":"operations","items":[{"title":"/api/rates/list","summary":"Get Rates","prefix":{"name":"post","color":"post"},"badges":[],"link":"/label-management/getratelist","deprecated":false},{"title":"/api/rates/buy","summary":"Buy Label","prefix":{"name":"get","color":"get"},"badges":[],"link":"/label-management/buylabel","deprecated":false},{"title":"/api/shipments/void","summary":"Void Label","prefix":{"name":"post","color":"post"},"badges":[],"link":"/label-management/voidlabel","deprecated":false},{"title":"/api/shipments/status","summary":"Get Billing & Void Status","prefix":{"name":"get","color":"get"},"badges":[],"link":"/label-management/getshipmentstatus","deprecated":false}]}]}]}]}},{"type":"group","label":"Address Validation","link":"/zh-hans/v1/ps_openapi/address-validation","routeSlug":"/zh-hans/v1/ps_openapi/address-validation","items":[{"label":"Verify Address","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v1/ps_openapi/address-validation/verifyaddress","routeSlug":"/zh-hans/v1/ps_openapi/address-validation/verifyaddress","metadata":{"seo":{"title":"Verify Address","description":"Validate and standardize a US shipping address against the address-service registry.Only the United States and its territories (PR, GU, VI, MP, MH, AS) are accepted —all other countries are rejected with HTTP 400."}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"verifyAddress","name":"Verify Address","isWebhook":false,"pointer":"/paths/~1api~1addresses~1verify/post","hasSamples":true},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Verify Address","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Validate and standardize a US shipping address against the address-service registry."},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Only the United States and its territories (PR, GU, VI, MP, MH, AS) are accepted —"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"all other countries are rejected with HTTP 400."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"How to interpret a 200 response"},"children":[]}]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Use the "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"errored"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" and "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"corrected"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" together. Apply"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"the rules in the order below — the first matching branch wins."},"children":[]}]}]},{"$$mdtype":"Node","type":"list","attributes":{"ordered":true,"marker":"."},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"errored == true"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" → Address is unusable"},"children":[]}]},{"$$mdtype":"Node","type":"hardbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Do "},"children":[]},{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"not"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" use the response fields as a shipping address. Prompt the user to"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"revise the input."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"errored == false && corrected == true"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" → Address is non-standard"},"children":[]}]},{"$$mdtype":"Node","type":"hardbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The submitted address is not in its standard form — for example, the city name"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"is misspelled, the ZIP code is wrong or incomplete, or street abbreviations /"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"casing are off. The service was able to identify the intended address and"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"return a standardized version. "},"children":[]},{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Strongly recommend the user update their"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"address before shipping."},"children":[]}]},{"$$mdtype":"Node","type":"hardbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The response fields ("},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"street"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"street2"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"city"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"state"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"zip"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"country"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":")"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"carry the "},"children":[]},{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"standardized address"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":". Surface them to the user (along with"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"corrections[]"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" for context) and suggest adopting this version as the final"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"shipping address. See the example below — the user typed the misspelled"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Bsoton"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", and the response returns the corrected "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Boston"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"."},"children":[]}]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"errored == false && corrected == false"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" → Fully valid"},"children":[]}]},{"$$mdtype":"Node","type":"hardbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The input matches the postal database exactly. Use it as-is — no confirmation needed."},"children":[]}]}]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Decision tree (pseudocode)"},"children":[]}]}]}]},{"$$mdtype":"Node","type":"fence","attributes":{"content":"if (errored) {\n  // Unusable — ask the user to revise\n} else if (corrected) {\n  // Usable — replace input with response fields,\n  // optionally surface corrections[] for user confirmation\n} else {\n  // Fully valid — use as-is\n}\n"},"children":[{"$$mdtype":"Node","type":"text","attributes":{"content":"if (errored) {\n  // Unusable — ask the user to revise\n} else if (corrected) {\n  // Usable — replace input with response fields,\n  // optionally surface corrections[] for user confirmation\n} else {\n  // Fully valid — use as-is\n}\n"},"children":[]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Additional fields"},"children":[]}]}]}]},{"$$mdtype":"Node","type":"list","attributes":{"ordered":false,"marker":"-"},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"residential"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" — whether the delivery point is residential. Defaults to "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"true"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" when the downstream service cannot determine it."},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"corrections[].message"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" / "},"children":[]},{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"errors[].message"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" — human-readable text"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"suitable for direct display to end users."},"children":[]}]}]}]}]},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Pass the API token as a Bearer token in the "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Authorization"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" header. Example: "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Authorization: Bearer <api_token>"},"children":[]}]}]}]}]},{"schemes":[{"name":"ApiTokenAuth","scopes":[],"type":"apiKey","in":"query","paramName":"api_token","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Pass the API token as a query parameter. Example: "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"?api_token=<api_token>"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"body","label":"Request Body","labelTranslationKey":"body","required":true,"mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/AddressVerifyRequest"}},"schemaId":"components/schemas/AddressVerifyRequest","pointer":"/paths/~1api~1addresses~1verify/post/requestBody"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"POST","path":"/api/addresses/verify","servers":[{"url":"https://ps-api.shipsaving.com","description":"Production server"},{"url":"https://ps-api.shipsaving.us","description":"Sandbox server"}],"parameters":{"path":[],"query":[],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer"}],"scopes":[]},{"schemes":[{"id":"ApiTokenAuth","type":"apiKey","name":"api_token","in":"query"}],"scopes":[]}],"requestBody":{"application/json":{"schemaId":"components/schemas/AddressVerifyRequest"}},"responseCodes":["200","400"],"pointer":"/api/addresses/verify","href":"address-validation/verifyaddress","openApiOperationId":"verifyAddress","summary":"Verify Address","securityGroups":[{"BearerAuth":[]},{"ApiTokenAuth":[]}]},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://ps-api.shipsaving.com","description":"Production server"},{"url":"https://ps-api.shipsaving.us","description":"Sandbox server"}],"schemaId":"components/schemas/AddressVerifyRequest","mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/AddressVerifyRequest"}},"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":"Address verification completed","mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/AddressVerifyResponse"}},"schemaId":"components/schemas/AddressVerifyResponse"},{"code":"400","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bad request — non-US country, missing required field, or validation service failure"},"children":[]}]}]}],"mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1addresses~1verify/post/responses/400/content/application~1json/examples/nonUsCountry","paths/~1api~1addresses~1verify/post/responses/400/content/application~1json/examples/missingField"]}},"schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1addresses~1verify/post/responses/400/content/application~1json/examples/nonUsCountry","paths/~1api~1addresses~1verify/post/responses/400/content/application~1json/examples/missingField"]}],"pointer":"/paths/~1api~1addresses~1verify/post/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"components/schemas/AddressVerifyResponse","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/AddressVerifyResponse"}}},{"code":"400","schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1addresses~1verify/post/responses/400/content/application~1json/examples/nonUsCountry","paths/~1api~1addresses~1verify/post/responses/400/content/application~1json/examples/missingField"],"mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/ErrorResponse","exampleIds":["paths/~1api~1addresses~1verify/post/responses/400/content/application~1json/examples/nonUsCountry","paths/~1api~1addresses~1verify/post/responses/400/content/application~1json/examples/missingField"]}}}],"examples":[]}]}]}]},"httpPath":"/api/addresses/verify"}],"content":{"contentType":"group","meta":{"name":"Address Validation"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Address Validation","showPageActions":true}],"panels":[{"children":[{"kind":"group-items","title":"Operations","titleTranslationKey":"operations","items":[{"title":"/api/addresses/verify","summary":"Verify Address","prefix":{"name":"post","color":"post"},"badges":[],"link":"/address-validation/verifyaddress","deprecated":false}]}]}]}]}},{"type":"group","label":"Carrier Management","link":"/zh-hans/v1/ps_openapi/carrier-management","routeSlug":"/zh-hans/v1/ps_openapi/carrier-management","items":[{"label":"Create UPS Ghost Account","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v1/ps_openapi/carrier-management/createupsghostaccount","routeSlug":"/zh-hans/v1/ps_openapi/carrier-management/createupsghostaccount","metadata":{"seo":{"title":"Create UPS Ghost Account","description":"Create a UPS shipper account on behalf of a merchant through ShipSaving,without requiring manual registration on the UPS website.The account is automatically linked to the merchant's ShipSaving companyand ready for shipping label purchases."}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"createUpsGhostAccount","name":"Create UPS Ghost Account","isWebhook":false,"pointer":"/paths/~1api~1carrier~1create_ups_ghost_account/post","hasSamples":true},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Create UPS Ghost Account","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Create a UPS shipper account on behalf of a merchant through ShipSaving,"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"without requiring manual registration on the UPS website."},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"The account is automatically linked to the merchant's ShipSaving company"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"and ready for shipping label purchases."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Important:"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" The address provided in this request will be used as the UPS default"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"return address — e.g. packages returned to sender will be delivered to this address."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"If an account with the same "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"seller_id"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" already exists, it will be soft-deleted"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"and a new one will be created with the updated address. This allows merchants"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"to change their return address by re-calling this endpoint."},"children":[]}]}]}]},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Pass the API token as a Bearer token in the "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Authorization"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" header. Example: "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Authorization: Bearer <api_token>"},"children":[]}]}]}]}]},{"schemes":[{"name":"ApiTokenAuth","scopes":[],"type":"apiKey","in":"query","paramName":"api_token","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Pass the API token as a query parameter. Example: "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"?api_token=<api_token>"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"body","label":"Request Body","labelTranslationKey":"body","required":true,"mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/UpsGhostAccountRequest"}},"schemaId":"components/schemas/UpsGhostAccountRequest","pointer":"/paths/~1api~1carrier~1create_ups_ghost_account/post/requestBody"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"POST","path":"/api/carrier/create_ups_ghost_account","servers":[{"url":"https://ps-api.shipsaving.com","description":"Production server"},{"url":"https://ps-api.shipsaving.us","description":"Sandbox server"}],"parameters":{"path":[],"query":[],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer"}],"scopes":[]},{"schemes":[{"id":"ApiTokenAuth","type":"apiKey","name":"api_token","in":"query"}],"scopes":[]}],"requestBody":{"application/json":{"schemaId":"components/schemas/UpsGhostAccountRequest"}},"responseCodes":["200","400"],"pointer":"/api/carrier/create_ups_ghost_account","href":"carrier-management/createupsghostaccount","openApiOperationId":"createUpsGhostAccount","summary":"Create UPS Ghost Account","securityGroups":[{"BearerAuth":[]},{"ApiTokenAuth":[]}]},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://ps-api.shipsaving.com","description":"Production server"},{"url":"https://ps-api.shipsaving.us","description":"Sandbox server"}],"schemaId":"components/schemas/UpsGhostAccountRequest","mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/UpsGhostAccountRequest"}},"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":"UPS ghost account created successfully","mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/CreateGhostAccountResponse"}},"schemaId":"components/schemas/CreateGhostAccountResponse"},{"code":"400","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bad request. Two distinct error shapes are possible:"},"children":[]}]}]},{"$$mdtype":"Node","type":"list","attributes":{"ordered":false,"marker":"-"},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Address has candidates"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" — the submitted address could not be matched"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"exactly, but UPS returned a list of likely candidates. Surface the"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"candidates to the user and re-submit with one of them."},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Identified by "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"code == \"ADDRESS_HAS_CANDIDATES\""},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"."},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Invalid address / generic validation error"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" — the address is"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"completely unusable, or another validation rule failed. Only "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"message"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"is returned."},"children":[]}]}]}]}],"mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"schema_226","exampleIds":["paths/~1api~1carrier~1create_ups_ghost_account/post/responses/400/content/application~1json/examples/addressHasCandidates","paths/~1api~1carrier~1create_ups_ghost_account/post/responses/400/content/application~1json/examples/invalidAddress"]}},"schemaId":"schema_226","exampleIds":["paths/~1api~1carrier~1create_ups_ghost_account/post/responses/400/content/application~1json/examples/addressHasCandidates","paths/~1api~1carrier~1create_ups_ghost_account/post/responses/400/content/application~1json/examples/invalidAddress"]}],"pointer":"/paths/~1api~1carrier~1create_ups_ghost_account/post/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"components/schemas/CreateGhostAccountResponse","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/CreateGhostAccountResponse"}}},{"code":"400","schemaId":"schema_226","exampleIds":["paths/~1api~1carrier~1create_ups_ghost_account/post/responses/400/content/application~1json/examples/addressHasCandidates","paths/~1api~1carrier~1create_ups_ghost_account/post/responses/400/content/application~1json/examples/invalidAddress"],"mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"schema_226","exampleIds":["paths/~1api~1carrier~1create_ups_ghost_account/post/responses/400/content/application~1json/examples/addressHasCandidates","paths/~1api~1carrier~1create_ups_ghost_account/post/responses/400/content/application~1json/examples/invalidAddress"]}}}],"examples":[]}]}]}]},"httpPath":"/api/carrier/create_ups_ghost_account"}],"content":{"contentType":"group","meta":{"name":"Carrier Management"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Carrier Management","showPageActions":true}],"panels":[{"children":[{"kind":"group-items","title":"Operations","titleTranslationKey":"operations","items":[{"title":"/api/carrier/create_ups_ghost_account","summary":"Create UPS Ghost Account","prefix":{"name":"post","color":"post"},"badges":[],"link":"/carrier-management/createupsghostaccount","deprecated":false}]}]}]}]}},{"type":"group","label":"Account Management","link":"/zh-hans/v1/ps_openapi/account-management","routeSlug":"/zh-hans/v1/ps_openapi/account-management","items":[{"label":"Get Account Balance","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v1/ps_openapi/account-management/querybalance","routeSlug":"/zh-hans/v1/ps_openapi/account-management/querybalance","metadata":{"seo":{"title":"Get Account Balance","description":"Retrieves real-time account balance in USD."}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"queryBalance","name":"Get Account Balance","isWebhook":false,"pointer":"/paths/~1api~1balance/get","hasSamples":false},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Get Account Balance","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":"Retrieves real-time account balance in USD.\n"},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Pass the API token as a Bearer token in the "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Authorization"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" header. Example: "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Authorization: Bearer <api_token>"},"children":[]}]}]}]}]},{"schemes":[{"name":"ApiTokenAuth","scopes":[],"type":"apiKey","in":"query","paramName":"api_token","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Pass the API token as a query parameter. Example: "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"?api_token=<api_token>"},"children":[]}]}]}]}]}]}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"GET","path":"/api/balance","servers":[{"url":"https://ps-api.shipsaving.com","description":"Production server"},{"url":"https://ps-api.shipsaving.us","description":"Sandbox server"}],"parameters":{"path":[],"query":[],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer"}],"scopes":[]},{"schemes":[{"id":"ApiTokenAuth","type":"apiKey","name":"api_token","in":"query"}],"scopes":[]}],"responseCodes":["200"],"pointer":"/api/balance","href":"account-management/querybalance","openApiOperationId":"queryBalance","summary":"Get Account Balance","securityGroups":[{"BearerAuth":[]},{"ApiTokenAuth":[]}]},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://ps-api.shipsaving.com","description":"Production server"},{"url":"https://ps-api.shipsaving.us","description":"Sandbox server"}],"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":"Successful response","mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"schema_227"}},"schemaId":"schema_227"}],"pointer":"/paths/~1api~1balance/get/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"schema_227","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"schema_227"}}}],"examples":[]}]}]}]},"httpPath":"/api/balance"}],"content":{"contentType":"group","meta":{"name":"Account Management"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"Account Management","showPageActions":true}],"panels":[{"children":[{"kind":"group-items","title":"Operations","titleTranslationKey":"operations","items":[{"title":"/api/balance","summary":"Get Account Balance","prefix":{"name":"get","color":"get"},"badges":[],"link":"/account-management/querybalance","deprecated":false}]}]}]}]}}],"store":{"schemaStore":{"components/schemas/RateListRequest":{"id":"components/schemas/RateListRequest","kind":"json-schema","title":"RateListRequest","data":{"type":"object","required":["from","to","shipments"],"properties":{"from":{"allOf":[{"$ref":"#/components/schemas/AddressBase"},{"description":"Shipper's (origin) address."}]},"to":{"allOf":[{"$ref":"#/components/schemas/Address"},{"description":"Recipient's (destination) address."}]},"shipments":{"type":"array","description":"One or more parcels to be rated.","items":{"$ref":"#/components/schemas/Parcel"}},"order":{"$ref":"#/components/schemas/OrderInfo"},"options":{"$ref":"#/components/schemas/ShippingOptions"},"seller_id":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Caller-defined unique identifier for a merchant or seller."},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"This is an open field — you may pass any value that uniquely identifies"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"a merchant on your platform (e.g., your internal merchant ID)."},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"At least one of "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"seller_id"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" or "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"carrier_account_id"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" must be provided."},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"When "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"carrier_account_id"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" is also provided, "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"carrier_account_id"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" takes priority"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"for account matching."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Note:"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" If the "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"seller_id"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" is not associated with a UPS 4th-party account,"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"rate quotes will still be returned, but label purchase will fail."},"children":[]}]}]}],"example":"merchant_10042"},"carrier_account_id":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Carrier account token in ShipSaving. You can obtain this value from the response of the Create Ghost Account endpoint,"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"or from the ShipSaving system → Carrier Accounts page (the \"Token\" column in the list)."},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"At least one of "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"seller_id"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" or "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"carrier_account_id"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" must be provided."},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"When both are provided, "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"carrier_account_id"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" takes priority."},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Note:"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" If the "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"carrier_account_id"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" is not associated with a UPS 4th-party account,"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"rate quotes will still be returned, but label purchase will fail."},"children":[]}]}]}],"example":"ca_bc28f2e7aaaa4bbbacccbf7d9f2c27xx"},"recipient_tax_ids":{"type":"array","description":"Recipient tax identification numbers for customs.","items":{"$ref":"#/components/schemas/TaxId"}}}}},"components/schemas/RateListResponse":{"id":"components/schemas/RateListResponse","kind":"json-schema","title":"RateListResponse","data":{"type":"object","properties":{"shipment_id":{"type":"string","description":"Shipment identifier for this rate group.","example":"ship_bea6cc8c-27f8-4dcf-915e-f6aeed8c5600"},"rate_id":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Unique rate identifier. Pass this to "},"children":[]},{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Buy Label"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" to purchase."},"children":[]}]}]}],"example":"rate_e50d02e2-047a-402c-aa32-22ad0926db00"},"provider":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Account provider — "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"shipsaving"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" (discounted) or "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"user"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" (own account)."},"children":[]}]}]}],"example":"shipsaving"},"account_name":{"type":"string","description":"Carrier account display name.","example":"USPS"},"carrier":{"type":"string","description":"Carrier name (USPS, UPS, FedEx, DHL, etc.).","example":"USPS"},"service":{"type":"string","description":"Service level name in uppercase.","example":"USPS_GROUND_ADVANTAGE"},"service_type":{"type":"string","description":"Service level code in lowercase.","example":"usps_ground_advantage"},"package":{"type":"string","description":"Package type name in uppercase.","example":"PACKAGE"},"package_type":{"type":"string","description":"Package type code in lowercase.","example":"my_package"},"delivery_days":{"type":"integer","description":"Estimated transit time in business days.","example":5},"published_rate":{"type":"number","format":"double","description":"Carrier's retail (list) rate before any discount.","example":10.9},"rate":{"type":"number","format":"double","description":"Your discounted rate.","example":8.99},"rebate":{"type":"number","format":"double","description":"Rebate amount credited back after purchase.","example":0.21},"insurance_fee":{"type":"number","format":"double","description":"Insurance fee if insurance was requested.","example":0},"zone":{"type":"string","description":"Carrier shipping zone.","example":"4"},"is_saturday_delivery":{"type":"boolean","description":"Whether the rate includes Saturday delivery.","example":false}}}},"components/schemas/BuyLabelResponse":{"id":"components/schemas/BuyLabelResponse","kind":"json-schema","title":"BuyLabelResponse","data":{"type":"object","properties":{"shipment_id":{"type":"integer","description":"Internal shipment record ID.","example":1245627},"packing_slip_number":{"type":"integer","description":"Packing slip number for the shipment.","example":109169},"master_tracking_code":{"type":"string","description":"Master tracking number for multi-piece shipments.","example":""},"prefix_tracking_code":{"type":"string","description":"Tracking number prefix (carrier-specific).","example":""},"tracking_code":{"type":"string","description":"Primary tracking number.","example":"1ZY50G652000880500"},"label_size":{"type":"string","description":"Label dimensions.","example":"4x6"},"label_type":{"type":"string","description":"Label output format used.","example":"png"},"length":{"type":"number","format":"double","description":"Package length in inches.","example":12},"width":{"type":"number","format":"double","description":"Package width in inches.","example":12},"height":{"type":"number","format":"double","description":"Package height in inches.","example":7},"weight":{"type":"number","format":"double","description":"Package weight in pounds.","example":14.99},"insurance":{"type":"number","format":"double","description":"Declared insurance value.","example":0},"insurance_fee":{"type":"object","description":"Insurance fee with currency.","properties":{"currency":{"type":"string","example":"USD"},"amount":{"type":"number","format":"double","example":0}}},"signature":{"type":"string","description":"Signature confirmation level applied.","example":"NO_SIGNATURE"},"custom_print1":{"type":"string","description":"First line of custom label text.","example":""},"custom_print2":{"type":"string","description":"Second line of custom label text.","example":""},"delivery_days":{"type":"integer","description":"Estimated transit time in business days.","example":1},"service_fee":{"type":"number","format":"double","description":"ShipSaving service fee.","example":0.05},"rate":{"type":"number","format":"double","description":"Your discounted shipping rate.","example":10.87},"rebate":{"type":"number","format":"double","description":"Rebate amount credited back.","example":0},"from_name":{"type":"string","description":"Sender's name.","example":"John Doe"},"from_company":{"type":"string","description":"Sender's company.","example":"ShipSaving, LLC"},"from_phone":{"type":"string","description":"Sender's phone number.","example":""},"from_street":{"type":"string","description":"Sender's street address.","example":"1600 Amphitheatre Parkway"},"from_street2":{"type":"string","description":"Sender's secondary address line.","example":""},"from_city":{"type":"string","description":"Sender's city.","example":"Mountain View"},"from_state":{"type":"string","description":"Sender's state.","example":"CA"},"from_zip":{"type":"string","description":"Sender's ZIP code.","example":"94043"},"from_country":{"type":"string","description":"Sender's country code.","example":"US"},"to_name":{"type":"string","description":"Recipient's name.","example":"Jane Smith"},"to_company":{"type":"string","description":"Recipient's company.","example":""},"to_phone":{"type":"string","description":"Recipient's phone number.","example":""},"to_street":{"type":"string","description":"Recipient's street address.","example":"350 Fifth Avenue"},"to_street2":{"type":"string","description":"Recipient's secondary address line.","example":""},"to_city":{"type":"string","description":"Recipient's city.","example":"New York"},"to_state":{"type":"string","description":"Recipient's state.","example":"NY"},"to_zip":{"type":"string","description":"Recipient's ZIP code.","example":"10118"},"to_country":{"type":"string","description":"Recipient's country code.","example":"US"},"label_status":{"type":"string","description":"Current label status.","example":"completed"},"warehouse_name":{"type":"string","description":"Warehouse name associated with the shipment.","example":"WH"},"store_name":{"type":"string","description":"Store name associated with the shipment.","example":""},"order_number":{"type":"string","description":"Linked order number.","example":""},"provider":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Account provider — "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"shipsaving"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" or "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"user"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"."},"children":[]}]}]}],"example":"shipsaving"},"carrier":{"type":"string","description":"Carrier name.","example":"UPS"},"service":{"type":"string","description":"Service level used.","example":"UPS_GROUND"},"package":{"type":"string","description":"Package type used.","example":"PACKAGE"},"published_rate":{"type":"number","format":"double","description":"Carrier's retail rate.","example":34.53},"label_url":{"type":"array","items":{"type":"string","format":"uri"},"nullable":true,"description":"Label image URLs.","example":["https://example.com/labels/2025-06-30/label_0.png"]},"commercial_invoice_url":{"type":"array","items":{"type":"string","format":"uri"},"nullable":true,"description":"Commercial invoice URLs for international shipments.","example":null}}}},"components/schemas/ShipmentStatusResponse":{"id":"components/schemas/ShipmentStatusResponse","kind":"json-schema","title":"ShipmentStatusResponse","data":{"type":"object","description":"Carrier billing state and void state of a single shipment.\n","properties":{"tracking_code":{"type":"string","description":"Tracking number of the matched shipment, echoed from the stored shipment record.\n","example":"1ZXXXXXXXXXXXX"},"bill_status":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Carrier billing state."},"children":[]}]}]},{"$$mdtype":"Node","type":"list","attributes":{"ordered":false,"marker":"-"},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"pending"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" — not yet reconciled; the state of a newly purchased label"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"ready"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" — queued for reconciliation"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"completed"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" — reconciled; "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"bill_rate"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" is final"},"children":[]}]}]}]}],"example":"completed"},"bill_rate":{"type":"number","format":"double","nullable":true,"description":"Amount actually billed by the carrier, in USD, always to two decimal places.\n","example":22.68},"void_status":{"type":"string","nullable":true,"description":"Void state of the label.","example":""},"adjust_time":{"type":"string","format":"date-time","nullable":true,"description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Timestamp of the most recent billing adjustment on this shipment, as an ISO-8601 UTC instant with second precision. "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"null"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" when the shipment has never been adjusted."},"children":[]}]}]}],"example":"2026-07-29T07:00:05Z"}}}},"components/schemas/UpsGhostAccountRequest":{"id":"components/schemas/UpsGhostAccountRequest","kind":"json-schema","title":"UpsGhostAccountRequest","data":{"type":"object","required":["seller_id","ip_address","first_name","last_name","email","phone","street1","city","state","country"],"properties":{"seller_id":{"type":"string","description":"Caller-defined unique identifier for a merchant or seller. Must be unique per UPS ghost account within the same company.\n","example":"merchant_10042"},"device_identity":{"type":"string","description":"Device fingerprint or identifier of the end user.","example":"d8a7b6c5-e4f3-2a1b-9c8d-7e6f5a4b3c2d"},"ip_address":{"type":"string","format":"ipv4","description":"IP address of the end user.","example":"203.0.113.42"},"first_name":{"type":"string","description":"Shipper's first name.","example":"John"},"last_name":{"type":"string","description":"Shipper's last name.","example":"Doe"},"email":{"type":"string","format":"email","description":"Shipper's email address.","example":"john@example.com"},"phone":{"type":"string","description":"Shipper's phone number.","example":"2135551234"},"company":{"type":"string","description":"Shipper's company name.","example":"Acme Corp"},"street1":{"type":"string","description":"First line of address. Accepts street address and PO boxes.","example":"1600 Amphitheatre Parkway"},"street2":{"type":"string","description":"Second line of address (suite, room, floor, apartment, etc.).","example":"Suite 200"},"city":{"type":"string","description":"City name.","example":"Mountain View"},"state":{"type":"string","description":"Two-character state/province code (e.g., CA, MA).\n","example":"CA"},"postcode":{"type":"string","description":"Postal code.","example":"94043"},"country":{"$ref":"#/components/schemas/Country"}}}},"components/schemas/AddressCandidatesError":{"id":"components/schemas/AddressCandidatesError","kind":"json-schema","title":"AddressCandidatesError","data":{"type":"object","description":"Returned with HTTP 400 when the submitted address could not be matched exactly but UPS suggested one or more candidate addresses. The caller should surface the candidates to the user, let them pick one, and re-submit the request with the corrected address.\n","required":["code","message","data"],"properties":{"code":{"type":"string","description":"Stable error code identifying this specific failure mode.","enum":["ADDRESS_HAS_CANDIDATES"],"example":"ADDRESS_HAS_CANDIDATES"},"message":{"type":"string","description":"Human-readable error message suitable for display to end users.","example":"The address you entered may be incorrect. Please choose one of the suggestions."},"data":{"type":"object","required":["addressType","candidates"],"properties":{"addressType":{"type":"string","description":"Which address on the ghost account triggered the candidate list.","example":"pickup"},"candidates":{"type":"array","description":"Suggested candidate addresses returned by UPS.","items":{"type":"object","properties":{"city":{"type":"string","example":"NEW YORK"},"stateOrProvinceCode":{"type":"string","description":"Two-character state or province code.","example":"NY"},"zipCode":{"type":"string","description":"ZIP or postal code.","example":"10001"},"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code.","example":"US"}}}}}}}}},"components/schemas/CreateGhostAccountResponse":{"id":"components/schemas/CreateGhostAccountResponse","kind":"json-schema","title":"CreateGhostAccountResponse","data":{"type":"object","properties":{"seller_id":{"type":"string","description":"The merchant identifier provided in the request.","example":"merchant_10042"},"carrier_account_id":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Carrier account token created in ShipSaving. Use this as the "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"carrier_token"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" in rate requests. This value can also be found in the ShipSaving system → Carrier Accounts page(the \"Token\" column in the list)."},"children":[]}]}]}],"example":"ca_bc28f2e7aaaa4bbbacccbf7d9f2c27xx"},"shipper_account_number":{"type":"string","description":"UPS shipper account number provisioned for this seller.","example":"Y5XXXX"}}}},"components/schemas/AddressVerifyRequest":{"id":"components/schemas/AddressVerifyRequest","kind":"json-schema","title":"AddressVerifyRequest","data":{"type":"object","required":["street","city","state","zip","country"],"properties":{"street":{"type":"string","description":"Primary street address.","example":"123 Main St"},"street2":{"type":"string","description":"Secondary address line (apartment, suite, unit, etc.). Optional.","example":"Apt 4B"},"city":{"type":"string","description":"City name.","example":"San Francisco"},"state":{"type":"string","description":"Two-character state or territory code.","example":"CA"},"zip":{"type":"string","description":"ZIP or postal code.","example":"94105"},"country":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Country identifier. Only the United States and its territories are accepted. The value may be the ISO 3166-1 alpha-2 code (e.g., "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"US"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"PR"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"GU"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"VI"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"MP"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"MH"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"AS"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":") or a recognized country name (case-insensitive), such as "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"United States"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"USA"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Puerto Rico"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Guam"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"US Virgin Islands"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Northern Mariana Islands"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Marshall Islands"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", or "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"American Samoa"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":". Other values are rejected with HTTP 400."},"children":[]}]}]}],"example":"US"}}}},"components/schemas/AddressVerifyResponse":{"id":"components/schemas/AddressVerifyResponse","kind":"json-schema","title":"AddressVerifyResponse","data":{"type":"object","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Verification result. Address fields ("},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"street"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"street2"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"city"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"state"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"zip"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":") reflect the standardized values when the address was matched, or echo the submitted values when it was not. The "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"residential"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" field is normalized to "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"true"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" when residential status cannot be determined."},"children":[]}]}]}],"properties":{"street":{"type":"string","description":"Standardized primary street address (or echo of input when not matched).","example":"1 MAIN ST"},"street2":{"type":"string","description":"Standardized secondary address line (or echo of input when not matched).","example":"STE 100"},"city":{"type":"string","description":"Standardized city name (or echo of input when not matched).","example":"ANYTOWN"},"state":{"type":"string","description":"Standardized state or territory code.","example":"CA"},"zip":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Standardized ZIP or postal code, typically expanded to ZIP+4 when matched."},"children":[]}]}]}],"example":"90001-1234"},"country":{"type":"string","description":"Country code.","example":"US"},"residential":{"type":"boolean","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Whether the address is residential. Defaults to "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"true"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" when residential status cannot be determined."},"children":[]}]}]}],"example":false},"errored":{"type":"boolean","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"true"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" when the address is unusable — either not found, or matched but requiring additional information (e.g., apartment/suite number). See "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"errors[]"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" for details."},"children":[]}]}]}],"example":false},"corrected":{"type":"boolean","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"true"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" when one or more fields were modified during standardization (e.g., corrected street spelling or ZIP code). See "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"corrections[]"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" for details."},"children":[]}]}]}],"example":false},"standardized":{"type":"boolean","nullable":true,"example":true},"corrections":{"type":"array","description":"Field-level corrections applied during standardization. Empty when no corrections were made.\n","items":{"$ref":"#/components/schemas/AddressVerifyMessage"},"example":[{"message":"Corrected ZIP Code"}]},"errors":{"type":"array","description":"Validation errors reported during address verification. Empty when the address is usable.","items":{"$ref":"#/components/schemas/AddressVerifyMessage"},"example":[]}}}},"components/schemas/AddressVerifyMessage":{"id":"components/schemas/AddressVerifyMessage","kind":"json-schema","title":"AddressVerifyMessage","data":{"type":"object","description":"A single human-readable note from address verification (used for both corrections and errors).","properties":{"message":{"type":"string","description":"Human-readable message describing a correction or error.","example":"Default address: The address you entered was found but more information is needed (such as an apartment, suite, or box number) to match to a specific address."}}}},"components/schemas/Country":{"id":"components/schemas/Country","kind":"json-schema","title":"Country","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Two-letter country code per "},"children":[]},{"$$mdtype":"Node","type":"link","inline":true,"attributes":{"href":"https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"ISO 3166-1 alpha-2"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"."},"children":[]}]}]}],"example":"US"}},"components/schemas/AddressBase":{"id":"components/schemas/AddressBase","kind":"json-schema","title":"AddressBase","data":{"type":"object","required":["name","street","city","state","zip","country"],"properties":{"name":{"type":"string","description":"Full name of the contact.","example":"John Doe"},"company":{"type":"string","description":"Company or organization name.","example":"Acme Corp"},"phone":{"type":"string","description":"Phone number. Required for international shipments.","example":"2135551234"},"email":{"type":"string","format":"email","description":"Email address.","example":"john@example.com"},"street":{"type":"string","description":"Primary street address.","example":"1600 Amphitheatre Parkway"},"street2":{"type":"string","description":"Secondary address line (apt, suite, unit, etc.).","example":"Suite 200"},"city":{"type":"string","description":"City name.","example":"Mountain View"},"state":{"type":"string","description":"State or province abbreviation.","example":"CA"},"zip":{"type":"string","description":"ZIP or postal code.","example":"94043"},"country":{"$ref":"#/components/schemas/Country"}}}},"components/schemas/Address":{"id":"components/schemas/Address","kind":"json-schema","title":"Address","data":{"allOf":[{"$ref":"#/components/schemas/AddressBase"},{"type":"object","properties":{"residential":{"type":"boolean","description":"Whether the address is residential. May affect the quoted rate.","example":false}}}]}},"components/schemas/CustomsItem":{"id":"components/schemas/CustomsItem","kind":"json-schema","title":"CustomsItem","data":{"type":"object","required":["weight","description","quantity","value","origin_country"],"properties":{"weight":{"type":"number","format":"double","description":"Item weight in pounds.","example":0.5},"description":{"type":"string","description":"Description of the item for customs clearance.","example":"Cotton T-Shirt"},"quantity":{"type":"integer","description":"Number of identical items.","example":2},"value":{"type":"number","format":"double","description":"Declared unit value in USD.","example":29.99},"hs_tariff_number":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Harmonized System (HS) tariff code. See "},"children":[]},{"$$mdtype":"Node","type":"link","inline":true,"attributes":{"href":"https://hts.usitc.gov/"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"USITC HTS"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" for reference."},"children":[]}]}]}],"example":"610910"},"origin_country":{"$ref":"#/components/schemas/Country"}}}},"components/schemas/Parcel":{"id":"components/schemas/Parcel","kind":"json-schema","title":"Parcel","data":{"type":"object","required":["weight"],"properties":{"length":{"type":"number","format":"double","description":"Package length in inches.","example":12},"width":{"type":"number","format":"double","description":"Package width in inches.","example":8},"height":{"type":"number","format":"double","description":"Package height in inches.","example":6},"weight":{"type":"number","format":"double","description":"Package weight in pounds.","example":2.5},"packages":{"type":"array","items":{"type":"string"},"description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Carrier predefined package types (e.g., "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"usps_small_flat_rate_box"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":")."},"children":[]}]}]}],"example":["usps_small_flat_rate_box"]},"insurance_amount":{"type":"number","format":"double","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Declared value for shipment insurance in USD. Must be used with "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"order.insurance_provider"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"."},"children":[]}]}]}],"example":150},"custom_print1":{"type":"string","description":"First line of custom text printed on the label (carrier support required).","example":"Order #12345"},"custom_print2":{"type":"string","description":"Second line of custom text printed on the label (carrier support required).","example":"Fragile"},"contents":{"type":"array","description":"Customs line items. Required for international shipments.","items":{"$ref":"#/components/schemas/CustomsItem"}}}}},"components/schemas/TaxId":{"id":"components/schemas/TaxId","kind":"json-schema","title":"TaxId","data":{"type":"object","properties":{"tax_id_type":{"type":"string","description":"Type of tax identification number.","enum":["TIN","EIN","SSN","VAT","EORI","IOSS","PAN","VOEC"],"example":"IOSS"},"tax_id_number":{"type":"string","description":"Tax identification number value.","example":"IM1234567890"},"tax_id_country":{"$ref":"#/components/schemas/Country"}}}},"components/schemas/OrderInfo":{"id":"components/schemas/OrderInfo","kind":"json-schema","title":"OrderInfo","data":{"type":"object","required":["warehouse_name"],"properties":{"warehouse_name":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Warehouse name as listed in your ShipSaving dashboard (Warehouses > Name)."},"children":[]}]}]}],"example":"WH"},"store_name":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Store nickname as listed in your ShipSaving dashboard (Stores > Store Nickname). Required when "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"order_number"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" is provided."},"children":[]}]}]}],"example":"My Shopify Store"},"order_number":{"type":"string","description":"Existing order number in ShipSaving. When provided, the label is linked to this order.","example":"20240201125047532"},"status":{"type":"string","description":"Order status to set after label purchase.","enum":["awaiting","hold","shipped"],"default":"awaiting"},"service_type":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Carrier service type code (e.g., "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"usps_ground_advantage"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":", "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"ups_ground"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":")."},"children":[]}]}]}],"example":"usps_ground_advantage"},"signature":{"type":"string","description":"Signature confirmation level.","enum":["NO_SIGNATURE","SIGNATURE","ADULT_SIGNATURE"],"example":"NO_SIGNATURE"},"insurance_provider":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Insurance provider. Must be used with "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"shipments[].insurance_amount"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"."},"children":[]}]}]}],"enum":["SHIPSURANCE","CARRIER"],"example":"SHIPSURANCE"},"contents_type":{"type":"string","description":"Customs contents category for international shipments.","enum":["GIFT","MERCHANDISE","SAMPLE","RETURNED_GOODS","DOCUMENTS"],"example":"MERCHANDISE"},"non_delivery_option":{"type":"string","description":"Action for undeliverable shipments.","enum":["RETURN","ABANDON"],"example":"RETURN"},"eel_pfc_type":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Electronic Export Information (EEI) filing method. "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"ITN"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" if an Internal Transaction Number was obtained via AES; "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"EXEMPTION_CODE"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" if the shipment qualifies for an EEI exemption."},"children":[]}]}]}],"enum":["ITN","EXEMPTION_CODE"]},"eel_pfc_code":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"ITN or exemption code corresponding to "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"eel_pfc_type"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"."},"children":[]}]}]}],"example":"X20250627012345"},"tax_ids":{"type":"array","description":"Tax identification numbers associated with the order.","items":{"$ref":"#/components/schemas/TaxId"}}}}},"components/schemas/ShippingOptions":{"id":"components/schemas/ShippingOptions","kind":"json-schema","title":"ShippingOptions","data":{"type":"object","properties":{"ship_date":{"type":"string","format":"date-time","description":"Ship date in ISO 8601 format with timezone offset.\n","example":"2025-02-07T10:55:56-08:00"},"require_saturday_delivery":{"type":"boolean","description":"Whether this shipment requires Saturday delivery.","example":false},"require_hazmat":{"type":"boolean","description":"Whether the shipment contains hazardous materials. Currently supported for USPS Ground Advantage and DHL eCommerce.\n","example":false},"hazmat_code":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Specifies the type of hazardous material. Use "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"usps_hazmat_820"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" for USPS shipments (Class 9 lithium batteries, unmarked package) and the "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"dhlecs_*"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" values for DHL eCommerce shipments. Shipments to or from U.S. offshore destinations (such as Guam, Puerto Rico) generally require "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"usps_hazmat_820"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" in order to ship lithium batteries. This parameter must be used in conjunction with "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"options.require_hazmat"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" to take effect."},"children":[]}]}]}],"enum":["usps_hazmat_820","dhlecs_lithium_metal_alloy_contained","dhlecs_lithium_metal_alloy_packed","dhlecs_lithium_metal_alloy_standalone","dhlecs_lithium_ion_contained","dhlecs_lithium_ion_packed","dhlecs_lithium_ion_standalone","dhlecs_limited_quantity","dhlecs_small_quantity_provision","dhlecs_limited_quantities_plt"]},"label_type":{"type":"string","description":"Label output format.","enum":["png","pdf"],"default":"png","example":"png"},"require_qr_code":{"type":"boolean","description":"Request a paperless label (QR code or barcode) instead of a standard label. Availability depends on carrier support.\n","example":false}}}},"components/schemas/ErrorResponse":{"id":"components/schemas/ErrorResponse","kind":"json-schema","title":"ErrorResponse","data":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message.","example":"Invalid request parameters."}}}},"schema_221":{"kind":"json-schema","data":{"type":"array","items":{"$ref":"#/components/schemas/RateListResponse"}},"id":"schema_221"},"schema_222":{"kind":"json-schema","data":{"type":"string"},"id":"schema_222"},"schema_223":{"kind":"json-schema","data":{"type":"array","items":{"$ref":"#/components/schemas/BuyLabelResponse"}},"id":"schema_223"},"schema_224":{"kind":"json-schema","data":{"type":"object","required":["tracking_code"],"properties":{"tracking_code":{"type":"string","description":"Tracking number of the shipment to void.","example":"9435811899562089111300"}}},"id":"schema_224"},"schema_225":{"kind":"json-schema","data":{"type":"object","properties":{"tracking_code":{"type":"string","description":"Tracking number of the voided shipment."}}},"id":"schema_225"},"schema_226":{"kind":"json-schema","data":{"oneOf":[{"$ref":"#/components/schemas/AddressCandidatesError"},{"$ref":"#/components/schemas/ErrorResponse"}]},"id":"schema_226"},"schema_227":{"kind":"json-schema","data":{"type":"object","properties":{"balance":{"type":"string","description":"Account balance","example":"173.13"},"currency":{"type":"string","description":"Currency. Only USD is supported.","example":"usd"}}},"id":"schema_227"}},"exampleStore":{"paths/~1api~1rates~1list/post/responses/400/content/application~1json/example":{"value":{"message":"Invalid request parameters."},"id":"paths/~1api~1rates~1list/post/responses/400/content/application~1json/example"},"paths/~1api~1rates~1buy/get/responses/400/content/application~1json/example":{"value":{"message":"Invalid request parameters."},"id":"paths/~1api~1rates~1buy/get/responses/400/content/application~1json/example"},"paths/~1api~1rates~1buy/get/responses/403/content/application~1json/example":{"value":{"message":"Exceed buy label limit, please contact support@shipsaving.com"},"id":"paths/~1api~1rates~1buy/get/responses/403/content/application~1json/example"},"paths/~1api~1shipments~1void/post/responses/200/content/application~1json/example":{"value":{"tracking_code":"9435811899562089111300"},"id":"paths/~1api~1shipments~1void/post/responses/200/content/application~1json/example"},"paths/~1api~1shipments~1void/post/responses/400/content/application~1json/example":{"value":{"message":"Invalid request parameters."},"id":"paths/~1api~1shipments~1void/post/responses/400/content/application~1json/example"},"paths/~1api~1shipments~1status/get/responses/200/content/application~1json/examples/billingCompleted":{"value":{"tracking_code":"1ZXXXXXXXXXXXXX","bill_status":"completed","bill_rate":22.68,"void_status":"","adjust_time":"2026-07-29T07:00:05Z"},"key":"billingCompleted","summary":"Billing reconciled, never voided","id":"paths/~1api~1shipments~1status/get/responses/200/content/application~1json/examples/billingCompleted"},"paths/~1api~1shipments~1status/get/responses/200/content/application~1json/examples/voidedAndRefunded":{"value":{"tracking_code":"1ZXXXXXXXXXXXXX","bill_status":"completed","bill_rate":22.68,"void_status":"refunded","adjust_time":null},"key":"voidedAndRefunded","summary":"Label voided and refunded","id":"paths/~1api~1shipments~1status/get/responses/200/content/application~1json/examples/voidedAndRefunded"},"paths/~1api~1shipments~1status/get/responses/400/content/application~1json/examples/missingTrackingCode":{"value":{"message":"Tracking code is required"},"key":"missingTrackingCode","summary":"tracking_code missing or blank","id":"paths/~1api~1shipments~1status/get/responses/400/content/application~1json/examples/missingTrackingCode"},"paths/~1api~1shipments~1status/get/responses/400/content/application~1json/examples/trackingCodeNotFound":{"value":{"message":"Tracking code does not exist"},"key":"trackingCodeNotFound","summary":"No matching shipment","id":"paths/~1api~1shipments~1status/get/responses/400/content/application~1json/examples/trackingCodeNotFound"},"paths/~1api~1addresses~1verify/post/responses/400/content/application~1json/examples/nonUsCountry":{"value":{"message":"Only US addresses are supported"},"key":"nonUsCountry","summary":"Non-US country","id":"paths/~1api~1addresses~1verify/post/responses/400/content/application~1json/examples/nonUsCountry"},"paths/~1api~1addresses~1verify/post/responses/400/content/application~1json/examples/missingField":{"value":{"message":"Street is required"},"key":"missingField","summary":"Missing required field","id":"paths/~1api~1addresses~1verify/post/responses/400/content/application~1json/examples/missingField"},"paths/~1api~1carrier~1create_ups_ghost_account/post/responses/400/content/application~1json/examples/addressHasCandidates":{"value":{"code":"ADDRESS_HAS_CANDIDATES","message":"The address you entered may be incorrect. Please choose one of the suggestions.","data":{"addressType":"pickup","candidates":[{"city":"ROCHESTER","stateOrProvinceCode":"NY","zipCode":"14624","countryCode":"US"},{"city":"NEW YORK","stateOrProvinceCode":"NY","zipCode":"10001","countryCode":"US"},{"city":"NEW YORK","stateOrProvinceCode":"NY","zipCode":"10002","countryCode":"US"}]}},"key":"addressHasCandidates","summary":"Address has candidates (suggestions available)","id":"paths/~1api~1carrier~1create_ups_ghost_account/post/responses/400/content/application~1json/examples/addressHasCandidates"},"paths/~1api~1carrier~1create_ups_ghost_account/post/responses/400/content/application~1json/examples/invalidAddress":{"value":{"message":"Missing or Invalid Billing Address.;Missing or Invalid Pickup Address."},"key":"invalidAddress","summary":"Address completely invalid","id":"paths/~1api~1carrier~1create_ups_ghost_account/post/responses/400/content/application~1json/examples/invalidAddress"}},"securitySchemeStore":{"BearerAuth":{"id":"BearerAuth","type":"http","scheme":"bearer","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Pass the API token as a Bearer token in the "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Authorization"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" header. Example: "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Authorization: Bearer <api_token>"},"children":[]}]}]}]},"ApiTokenAuth":{"id":"ApiTokenAuth","type":"apiKey","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Pass the API token as a query parameter. Example: "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"?api_token=<api_token>"},"children":[]}]}]}],"in":"query","paramName":"api_token"}},"servers":[{"url":"https://ps-api.shipsaving.com","description":"Production server"},{"url":"https://ps-api.shipsaving.us","description":"Sandbox server"}]},"options":{"hideDownloadButtons":true,"hideReplay":true,"feedback":{"hide":true,"settings":{"label":""}},"hideSidebar":true,"mockServer":{"off":true},"disableRouter":true,"downloadUrls":[{"url":"/_bundle/@l10n/zh-Hans/v1/ps_openapi.json?download"},{"url":"/_bundle/@l10n/zh-Hans/v1/ps_openapi.yaml?download"}],"excludeFromSearch":false,"specType":"openapi","markdocOptions":{"tags":{},"nodes":{},"components":{}},"metadata":{"title":"UPS 4th Party API Integration","description":"This document outlines the integration of ShipSaving APIs under the UPS 4th party account model, including account creation, label generation, and other workflows. \n"}},"baseSlug":"/zh-hans/v1/ps_openapi","routesMapping":{}}