openapi: 3.0.0 info: title: ShipEngine API version: 1.1.202405011605 termsOfService: 'https://www.shipengine.com/terms-of-service/' x-logo: url: 'https://shipengine.github.io/img/shipengine-logo-square.png' backgroundColor: '#FFFFFF' altText: ShipEngine logo contact: name: ShipEngine Sales & Support email: sales@shipengine.com url: 'https://www.shipengine.com/contact/' x-phone: 1-512-856-5379 description: > ShipEngine's easy-to-use REST API lets you manage all of your shipping needs without worrying about the complexities of different carrier APIs and protocols. We handle all the heavy lifting so you can focus on providing a first-class shipping experience for your customers at the best possible prices. Each of ShipEngine's features can be used by itself or in conjunction with each other to build powerful shipping functionality into your application or service. ## Getting Started If you're new to REST APIs then be sure to read our [introduction to REST](https://www.shipengine.com/docs/rest/) to understand the basics. Learn how to [authenticate yourself to ShipEngine](https://www.shipengine.com/docs/auth/), and then use our [sandbox environment](https://www.shipengine.com/docs/sandbox/) to kick the tires and get familiar with our API. If you run into any problems, then be sure to check the [error handling guide](https://www.shipengine.com/docs/errors/) for tips. Here are some step-by-step **tutorials** to get you started: - [Learn how to create your first shipping label](https://www.shipengine.com/docs/labels/create-a-label/) - [Calculate shipping costs and compare rates across carriers](https://www.shipengine.com/docs/rates/) - [Track packages on-demand or in real time](https://www.shipengine.com/docs/tracking/) - [Validate mailing addresses anywhere on Earth](https://www.shipengine.com/docs/addresses/validation/) ## Shipping Labels for Every Major Carrier ShipEngine makes it easy to [create shipping labels for any carrier](https://www.shipengine.com/docs/labels/create-a-label/) and [download them](https://www.shipengine.com/docs/labels/downloading/) in a [variety of file formats](https://www.shipengine.com/docs/labels/formats/). You can even customize labels with your own [messages](https://www.shipengine.com/docs/labels/messages/) and [images](https://www.shipengine.com/docs/labels/branding/). ## Real-Time Package Tracking With ShipEngine you can [get the current status of a package](https://www.shipengine.com/docs/tracking/) or [subscribe to real-time tracking updates](https://www.shipengine.com/docs/tracking/webhooks/) via webhooks. You can also create [custimized tracking pages](https://www.shipengine.com/docs/tracking/branded-tracking-page/) with your own branding so your customers will always know where their package is. ## Compare Shipping Costs Across Carriers Make sure you ship as cost-effectively as possible by [comparing rates across carriers](https://www.shipengine.com/docs/rates/get-shipment-rates/) using the ShipEngine Rates API. Or if you don't know the full shipment details yet, then you can [get rate estimates](https://www.shipengine.com/docs/rates/estimate/) with limited address info. ## Worldwide Address Validation ShipEngine supports [address validation](https://www.shipengine.com/docs/addresses/validation/) for virtually [every country on Earth](https://www.shipengine.com/docs/addresses/validation/countries/), including the United States, Canada, Great Britain, Australia, Germany, France, Norway, Spain, Sweden, Israel, Italy, and over 160 others. paths: /v1/account/settings: summary: Account settings description: ShipEngine Account settings get: summary: List Account Settings description: List all account settings for the ShipEngine account tags: - account operationId: list_account_settings responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_account_settings_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/account/settings/images: summary: Account settings images description: ShipEngine Account images get: summary: List Account Images description: List all account images for the ShipEngine account tags: - account operationId: list_account_images responses: '200': description: The request was a success. content: application/json: schema: $ref: >- #/components/schemas/list_account_settings_images_response_body '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' post: summary: Create an Account Image description: Create an Account Image tags: - account operationId: create_account_image requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/create_account_settings_image_request_body' responses: '200': description: The requested object creation was a success. content: application/json: schema: $ref: '#/components/schemas/get_account_settings_images_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/account/settings/images/{label_image_id}': summary: Account settings images description: ShipEngine Account images get: summary: Get Account Image By ID description: Retrieve information for an account image. tags: - account operationId: get_account_settings_images_by_id parameters: - name: label_image_id in: path required: true schema: $ref: '#/components/schemas/image_id' description: Label Image Id responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_account_settings_images_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' put: summary: Update Account Image By ID description: Update information for an account image. tags: - account operationId: update_account_settings_images_by_id parameters: - name: label_image_id in: path required: true schema: $ref: '#/components/schemas/image_id' description: Label Image Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/update_account_settings_image_request_body' responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' delete: summary: Delete Account Image By Id description: Delete Account Image By Id tags: - account operationId: delete_account_image_by_id parameters: - name: label_image_id in: path required: true schema: $ref: '#/components/schemas/image_id' description: Label Image Id responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/addresses/recognize: summary: Parse an address description: > Data often enters your system as unstructured text (for example: emails, SMS messages, support tickets, or other documents). ShipEngine's address-recognition API helps you extract meaningful address data (e.g. recipient name, address line 1, line 2, city, postal code) from this unstructured text. put: summary: Parse an address description: > The address-recognition API makes it easy for you to extract address data from unstructured text, including the recipient name, line 1, line 2, city, postal code, and more. Data often enters your system as unstructured text (for example: emails, SMS messages, support tickets, or other documents). ShipEngine's address-recognition API helps you extract meaningful, structured data from this unstructured text. The parsed address data is returned in the same structure that's used for other ShipEngine APIs, such as address validation, rate quotes, and shipping labels. > **Note:** Address recognition is currently supported for the United States, Canada, Australia, New Zealand, the United Kingdom, and Ireland. tags: - addresses operationId: parse_address requestBody: required: true description: > The only required field is `text`, which is the text to be parsed. You can optionally also provide an `address` containing already-known values. For example, you may already know the recipient's name, city, and country, and only want to parse the street address into separate lines. content: application/json: schema: $ref: '#/components/schemas/parse_address_request_body' examples: text_only: summary: Text only description: > This is the simplest way to call the address-recognition API. Just pass the text to be parsed and nothing else. value: text: >- Margie McMiller at 3800 North Lamar suite 200 in austin, tx. The zip code there is 78652. some_known_fields: summary: Some known fields description: > You can optionally provide an `address` object containing any already-known values. For example, you may already know the recipient's name, city, and country, and only want to parse the street address into separate lines. value: text: >- Margie McMiller at 3800 North Lamar suite 200 in austin, tx. The zip code there is 78652. address: country_code: US address_residential_indicator: 'yes' responses: '200': description: > Returns the parsed address, as well as a confidence score and a list of all the entities that were recognized in the text. content: application/json: schema: $ref: '#/components/schemas/parse_address_response_body' examples: text_only: description: > This response shows that the address-recognition API was able to recognize all the address entities in the text. Notice that the `country_code` is not populated and the `address_residential_indicator` is "unknown", since neither of these fields was included in the text. value: score: 0.9122137426845613 address: name: Margie McMiller address_line1: 3800 North Lamar address_line2: Suite 200 city_locality: Austin state_province: TX postal_code: 78652 address_residential_indicator: unknown entities: - type: person score: 0.9519646137063122 text: Margie McMiller start_index: 0 end_index: 14 result: value: Margie McMiller - type: address_line score: 0.9805313966503588 text: 3800 North Lamar start_index: 19 end_index: 34 result: line: 1 value: 3800 North Lamar - type: number score: 0.9805313966503588 text: 3800 start_index: 19 end_index: 22 result: type: cardinal value: 3800 - type: address_line score: 1 text: suite 200 start_index: 36 end_index: 44 result: line: 2 value: Suite 200 - type: number score: 0.9805313966503588 text: 200 start_index: 42 end_index: 44 result: type: cardinal value: 200 - type: city_locality score: 0.9805313966503588 text: austin start_index: 49 end_index: 54 result: value: Austin - type: state_province score: 0.6082904353940255 text: tx start_index: 57 end_index: 58 result: name: Texas value: TX - type: postal_code score: 0.9519646137063122 text: 78652 start_index: 84 end_index: 88 result: value: 78652 some_known_fields: description: > This response is shows that the address-recognition API was able to recognize all the address entities in the text. Notice that the `country_code` and `address_residential_indicator` fields are populated with the values that were provided in the request. value: score: 0.9122137426845613 address: name: Margie McMiller address_line1: 3800 North Lamar address_line2: Suite 200 city_locality: Austin state_province: TX postal_code: 78652 country_code: US address_residential_indicator: 'yes' entities: - type: person score: 0.9519646137063122 text: Margie McMiller start_index: 0 end_index: 14 result: value: Margie McMiller - type: address_line score: 0.9805313966503588 text: 3800 North Lamar start_index: 19 end_index: 34 result: line: 1 value: 3800 North Lamar - type: number score: 0.9805313966503588 text: 3800 start_index: 19 end_index: 22 result: type: cardinal value: 3800 - type: address_line score: 1 text: suite 200 start_index: 36 end_index: 44 result: line: 2 value: Suite 200 - type: number score: 0.9805313966503588 text: 200 start_index: 42 end_index: 44 result: type: cardinal value: 200 - type: city_locality score: 0.9805313966503588 text: austin start_index: 49 end_index: 54 result: value: Austin - type: state_province score: 0.6082904353940255 text: tx start_index: 57 end_index: 58 result: name: Texas value: TX - type: postal_code score: 0.9519646137063122 text: 78652 start_index: 84 end_index: 88 result: value: 78652 '400': $ref: '#/components/responses/400_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/addresses/validate: summary: Address Validation description: > Address validation ensures accurate addresses and can lead to reduced shipping costs by preventing address correction surcharges. ShipEngine cross references multiple databases to validate addresses and identify potential deliverability issues. post: summary: Validate An Address description: > Address validation ensures accurate addresses and can lead to reduced shipping costs by preventing address correction surcharges. ShipEngine cross references multiple databases to validate addresses and identify potential deliverability issues. tags: - addresses operationId: validate_address requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/validate_address_request_body' examples: all_known_fields_request: summary: All Known Fields description: A call that returns a status of `verified`. value: - name: Mickey and Minnie Mouse phone: 714-781-4565 company_name: The Walt Disney Company address_line1: 500 South Buena Vista Street city_locality: Burbank state_province: CA postal_code: 91521 country_code: US responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/validate_address_response_body' examples: all_known_fields: summary: All Known Fields description: A response for a `verified` status call. value: - status: verified original_address: name: Mickey and Minnie Mouse phone: 714-781-4565 company_name: The Walt Disney Company address_line1: 500 South Buena Vista Street address_line2: null address_line3: null city_locality: Burbank state_province: CA postal_code: 91521 country_code: US address_residential_indicator: unknown matched_address: name: MICKEY AND MINNIE MOUSE phone: 714-781-4565 company_name: THE WALT DISNEY COMPANY address_line1: 500 S BUENA VISTA ST address_line2: null address_line3: null city_locality: BURBANK state_province: CA postal_code: 91521-0007 country_code: US address_residential_indicator: 'no' messages: [] empty_fields: summary: Empty Fields description: A response for an `unverified` API Call with error message value: - status: unverified original_address: name: null phone: null company_name: null address_line1: null address_line2: null address_line3: null city_locality: null state_province: null postal_code: null country_code: null address_residential_indicator: unknown matched_address: null messages: - code: a1001 message: >- country_code is not currently a supported country please check the documentation for acceptable 2-letter country codes. type: error detail_code: unsupported_country '400': $ref: '#/components/responses/400_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/batches: summary: Batches description: > Batches are an advanced feature of ShipEngine designed for users who need to generate hundreds or thousands of labels at a time. When ShipEngine generates labels it relies on many carriers, their services, their dependencies, and a number of other variables to fulfill your requests; those requests can take a few minutes for us to get back to you. get: summary: List Batches description: List Batches associated with your Shipengine account operationId: list_batches tags: - batches parameters: - name: status in: query required: false schema: $ref: '#/components/schemas/batch_status' - name: page in: query required: false schema: type: integer format: int32 minimum: 1 default: 1 example: 2 description: > Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned. - name: page_size in: query required: false schema: type: integer format: int32 minimum: 1 default: 25 example: 50 description: The number of results to return per response. - name: sort_dir in: query required: false schema: allOf: - $ref: '#/components/schemas/sort_dir' default: desc description: Controls the sort order of the query. - name: batch_number in: query required: false schema: type: string description: Batch Number - name: sort_by in: query required: false schema: $ref: '#/components/schemas/batches_sort_by' responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/list_batches_response_body' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' post: summary: Create A Batch description: Create a Batch tags: - batches operationId: create_batch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/create_batch_request' responses: '200': description: The requested object creation was a success. content: application/json: schema: $ref: '#/components/schemas/create_batch_response_body' '207': description: >- The request was a partial success. It contains results, as well as processing errors. content: application/json: schema: $ref: '#/components/schemas/create_batch_response_body' '400': $ref: '#/components/responses/400_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/batches/external_batch_id/{external_batch_id}': summary: External Batch ID description: Retrive a batch from an external batch ID parameters: - name: external_batch_id in: path required: true schema: type: string example: 13553d7f-3c87-4771-bae1-c49bacef11cb get: summary: Get Batch By External ID description: Get Batch By External ID tags: - batches operationId: get_batch_by_external_id responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_batch_by_external_id_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/batches/{batch_id}': summary: Batch By ID description: Check the status of your batch by retrieving it with a Batch ID. parameters: - name: batch_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Batch ID delete: summary: Delete Batch By Id description: Delete Batch By Id operationId: delete_batch tags: - batches responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' get: summary: Get Batch By ID description: Get Batch By ID tags: - batches operationId: get_batch_by_id responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_batch_by_id_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' put: summary: Update Batch By Id description: Update Batch By Id operationId: update_batch tags: - batches responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/batches/{batch_id}/add': summary: Add Funds to a Carrier description: > You can check your balance for a particular carrier by calling [List Carriers](https://www.shipengine.com/docs/reference/list-carriers/) endpoint. For any carrier account where requires_funded_amount is true, you can add funds. parameters: - name: batch_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Batch ID post: summary: Add to a Batch description: Add a Shipment or Rate to a Batch tags: - batches operationId: add_to_batch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/add_to_batch_request_body' responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/batches/{batch_id}/errors': summary: Batch Errors description: > Error handling in batches are handled differently than in a single synchronous request. You must retrieve the status of your batch by [getting a batch](https://www.shipengine.com/docs/reference/get-batch-by-id/) and getting an overview of the statuses or you can list errors directly here below to get detailed information about the errors. parameters: - name: batch_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Batch ID get: summary: Get Batch Errors description: > Error handling in batches are handled differently than in a single synchronous request. You must retrieve the status of your batch by [getting a batch](https://www.shipengine.com/docs/reference/get-batch-by-id/) and getting an overview of the statuses or you can list errors directly here below to get detailed information about the errors. tags: - batches operationId: list_batch_errors parameters: - name: page in: query required: false schema: type: integer format: int32 minimum: 1 default: 1 example: 2 description: > Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned. - name: pagesize in: query required: false schema: type: integer format: int32 minimum: 1 responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/list_batch_errors_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/batches/{batch_id}/process/labels': summary: Process Batch ID Labels description: Process Batch ID Labels parameters: - name: batch_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Batch ID post: summary: Process Batch ID Labels description: Process Batch ID Labels tags: - batches operationId: process_batch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/process_batch_request_body' responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/batches/{batch_id}/remove': summary: Remove Batch By ID description: Remove a list of shipments from a batch parameters: - name: batch_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Batch ID post: summary: Remove From Batch description: Remove a shipment or rate from a batch tags: - batches operationId: remove_from_batch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/remove_from_batch_request_body' responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/carriers: summary: Carriers description: > Carriers are a company or individual that specializes in transporting freight from one destination to another. Shipengine allows you to easily integrate with multiple carriers so you can chose the shipping option that is right for you. get: summary: List Carriers description: List all carriers that have been added to this account tags: - carriers operationId: list_carriers responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_carriers_response_body' '207': description: >- The request was a partial success. It contains results, as well as errors. content: application/json: schema: $ref: '#/components/schemas/get_carriers_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/carriers/{carrier_id}': summary: Individual carriers description: >- Perform actions and get information on individual carriers connected with your account. parameters: - name: carrier_id in: path required: true schema: $ref: '#/components/schemas/se_id' example: se-28529731 description: Carrier ID get: summary: Get Carrier By ID description: Retrive carrier info by ID tags: - carriers operationId: get_carrier_by_id responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_carrier_by_id_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' delete: summary: Disconnect Carrier by ID description: Disconnect a Carrier of the given ID from the account tags: - carriers operationId: disconnect_carrier_by_id responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/carriers/{carrier_id}/add_funds': summary: Carrier Funds description: >- All carriers require that funds to be attached to an account to ensure payment for the various services they provide to their customers. parameters: - name: carrier_id in: path required: true schema: $ref: '#/components/schemas/se_id' example: se-28529731 description: Carrier ID put: summary: Add Funds To Carrier description: Add Funds To A Carrier tags: - carriers operationId: add_funds_to_carrier requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/add_funds_to_carrier_request_body' responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/add_funds_to_carrier_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/carriers/{carrier_id}/options': summary: Carrier Options description: >- Carriers support various options for particular shipments. Ex. (non-machinable, is_alcohol, fragile, etc) parameters: - name: carrier_id in: path required: true schema: $ref: '#/components/schemas/se_id' example: se-28529731 description: Carrier ID get: summary: Get Carrier Options description: Get a list of the options available for the carrier tags: - carriers operationId: get_carrier_options responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_carrier_options_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/carriers/{carrier_id}/packages': summary: Carrier Packages description: > Carriers support many different package types, Shipengine supports retrieving all available package so that you can best determine what is right for your particular shipment. parameters: - name: carrier_id in: path required: true schema: $ref: '#/components/schemas/se_id' example: se-28529731 description: Carrier ID get: summary: List Carrier Package Types description: List the package types associated with the carrier tags: - carriers operationId: list_carrier_package_types responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/list_carrier_package_types_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/carriers/{carrier_id}/services': summary: Carrier Services description: > Carrier services usually refer to the various shipping options that a carrier provides to its customers. Ex. Priority mail, overnight, international parameters: - name: carrier_id in: path required: true schema: $ref: '#/components/schemas/se_id' example: se-28529731 description: Carrier ID get: summary: List Carrier Services description: List the services associated with the carrier ID tags: - carriers operationId: list_carrier_services responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/list_carrier_services_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/connections/carriers/{carrier_name}': summary: Carrier connections description: Carrier connections parameters: - name: carrier_name in: path required: true schema: $ref: '#/components/schemas/carrier_name' example: dhl_express description: >- The carrier name, such as `stamps_com`, `ups`, `fedex`, or `dhl_express`. post: summary: Connect a carrier account description: Connect a carrier account tags: - carrier_accounts operationId: connect_carrier requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/connect_carrier_request_body' responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/connect_carrier_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/connections/carriers/{carrier_name}/{carrier_id}': summary: Disconnect a carrier description: Disconnect a carrier parameters: - name: carrier_name in: path required: true schema: $ref: '#/components/schemas/carrier_name' example: dhl_express description: >- The carrier name, such as `stamps_com`, `ups`, `fedex`, or `dhl_express`. - name: carrier_id in: path required: true schema: $ref: '#/components/schemas/se_id' example: se-28529731 description: Carrier ID delete: summary: Disconnect a carrier description: Disconnect a carrier tags: - carrier_accounts operationId: disconnect_carrier responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/connections/carriers/{carrier_name}/{carrier_id}/settings': summary: Carrier settings description: Carrier settings parameters: - name: carrier_name in: path required: true schema: $ref: '#/components/schemas/carrier_name_with_settings' example: dhl_express description: 'The carrier name, such as `ups`, `fedex`, or `dhl_express`.' - name: carrier_id in: path required: true schema: $ref: '#/components/schemas/se_id' example: se-28529731 description: Carrier ID get: summary: Get carrier settings description: Get carrier settings tags: - carrier_accounts operationId: get_carrier_settings responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_carrier_settings_response_body' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' put: summary: Update carrier settings description: Update carrier settings tags: - carrier_accounts operationId: update_carrier_settings requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/update_carrier_settings_request_body' responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/connections/insurance/shipsurance: summary: Shipsurance Connection description: Shipsurance Connection delete: summary: Disconnect a Shipsurance Account description: Disconnect a Shipsurance Account operationId: disconnect_insurer tags: - insurance responses: '200': description: The request was a success content: application/json: schema: $ref: '#/components/schemas/disconnect_insurer_response_body' '400': $ref: '#/components/responses/400_error_response' '500': $ref: '#/components/responses/500_error_response' post: summary: Connect a Shipsurance Account description: Connect a Shipsurance Account operationId: connect_insurer tags: - insurance requestBody: content: application/json: schema: $ref: '#/components/schemas/connect_insurer_request_body' required: true responses: '200': description: The request was a success content: application/json: schema: $ref: '#/components/schemas/connect_insurer_response_body' '400': $ref: '#/components/responses/400_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/downloads/{dir}/{subdir}/{filename}': summary: File Download description: > This endpoint is used to download forms that are generated in the various pdf, png, zpl formats such as labels and batches parameters: - name: subdir in: path required: true schema: type: string - name: filename in: path required: true schema: type: string - name: dir in: path required: true schema: type: string get: summary: Download File description: Get File operationId: download_file tags: - downloads parameters: - name: download in: query required: false schema: type: string - name: rotation in: query required: false schema: type: integer format: int32 responses: '200': description: The request was a success content: application/pdf: schema: $ref: '#/components/schemas/download_file_pdf_response_body' image/png: schema: $ref: '#/components/schemas/download_file_png_response_body' application/zpl: schema: $ref: '#/components/schemas/download_file_zpl_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/environment/webhooks: summary: Webhooks description: > ShipEngine exposes asynchronous operations for long running operations such as batch labels and rates. Webhooks allow the ShipEngine servers to contact your servers when an operation changes state, such as a batch label creation completion. get: summary: List Webhooks description: List all webhooks currently enabled for the account. tags: - webhooks operationId: list_webhooks responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/list_webhooks_response_body' '400': $ref: '#/components/responses/400_error_response' '500': $ref: '#/components/responses/500_error_response' post: summary: Create a Webhook description: Create a webook for specific events in the environment. tags: - webhooks operationId: create_webhook requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/create_webhook_request_body' responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/create_webhook_response_body' '400': $ref: '#/components/responses/400_error_response' '409': $ref: '#/components/responses/409_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/environment/webhooks/{webhook_id}': summary: Webhook description: 'Retrieve, update, and delete information for individual webhooks' parameters: - name: webhook_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Webhook ID get: summary: Get Webhook By ID description: Retrieve individual webhook by an ID tags: - webhooks operationId: get_webhook_by_id responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_webhook_by_id_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' put: summary: Update a Webhook description: Update the webhook url property tags: - webhooks operationId: update_webhook requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/update_webhook_request_body' responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' delete: summary: Delete Webhook By ID description: Delete a webhook tags: - webhooks operationId: delete_webhook responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/insurance/shipsurance/add_funds: summary: Shipsurance description: > [Shipsurance](https://www.shipsurance.com/) is a shipping insurance company offering coverage for shipments sent via the major shipping carriers worldwide. patch: summary: Add Funds To Insurance description: > You may need to auto fund your account from time to time. For example, if you don't normally ship items over $100, and may want to add funds to insurance rather than keeping the account funded. tags: - insurance operationId: add_funds_to_insurance requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/add_funds_to_insurance_request_body' responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/add_funds_to_insurance_response_body' '400': $ref: '#/components/responses/400_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/insurance/shipsurance/balance: summary: Shipsurance description: > [Shipsurance](https://www.shipsurance.com/) is a shipping insurance company offering coverage for shipments sent via the major shipping carriers worldwide. get: summary: Get Insurance Funds Balance description: Retrieve the balance of your Shipsurance account. tags: - insurance operationId: get_insurance_balance responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_insurance_balance_response_body' '400': $ref: '#/components/responses/400_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/labels: summary: Print shipping labels description: > Print shipping labels for any of the top global carriers in minutes—instead of weeks. Simply [connect your existing carrier accounts](https://www.shipengine.com/docs/carriers/setup/) in the API dashboard, and then [begin creating labels](https://www.shipengine.com/docs/shipping/use-a-carrier-service/). get: summary: List labels description: > This endpoint returns a list of labels that you've [created](https://www.shipengine.com/docs/labels/create-a-label/). You can optionally filter the results as well as control their sort order and the number of results returned at a time. By default, all labels are returned, 25 at a time, starting with the most recently created ones. You can combine multiple filter options to narrow-down the results. For example, if you only want to get your UPS labels for your east coast warehouse you could query by both `warehouse_id` and `carrier_id` tags: - labels operationId: list_labels parameters: - name: label_status in: query required: false schema: $ref: '#/components/schemas/label_status' description: Only return labels that are currently in the specified status - name: service_code in: query required: false schema: $ref: '#/components/schemas/service_code' example: usps_first_class_mail description: >- Only return labels for a specific [carrier service](https://www.shipengine.com/docs/shipping/use-a-carrier-service/) - description: >- Only return labels for a specific [carrier account](https://www.shipengine.com/docs/carriers/setup/) name: carrier_id in: query required: false schema: $ref: '#/components/schemas/se_id' - description: Only return labels with a specific tracking number name: tracking_number in: query required: false schema: type: string minLength: 1 example: '9405511899223197428490' - description: >- Only return labels that were created in a specific [batch](https://www.shipengine.com/docs/labels/bulk/) name: batch_id in: query required: false schema: $ref: '#/components/schemas/se_id' - name: rate_id in: query required: false schema: $ref: '#/components/schemas/se_id' description: Rate ID - name: shipment_id in: query required: false schema: $ref: '#/components/schemas/se_id' description: Shipment ID - description: >- Only return labels that originate from a specific [warehouse](https://www.shipengine.com/docs/shipping/ship-from-a-warehouse/) name: warehouse_id in: query required: false schema: $ref: '#/components/schemas/se_id' - description: >- Only return labels that were created on or after a specific date/time name: created_at_start in: query required: false schema: type: string format: date-time example: '2019-03-12T19:24:13.657Z' - description: >- Only return labels that were created on or before a specific date/time name: created_at_end in: query required: false schema: type: string format: date-time example: '2019-03-12T19:24:13.657Z' - name: page in: query required: false schema: type: integer format: int32 minimum: 1 default: 1 example: 2 description: > Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned. - name: page_size in: query required: false schema: type: integer format: int32 minimum: 1 default: 25 example: 50 description: The number of results to return per response. - name: sort_dir in: query required: false schema: allOf: - $ref: '#/components/schemas/sort_dir' default: desc description: Controls the sort order of the query. - name: sort_by in: query required: false schema: type: string enum: - modified_at - created_at default: created_at description: Controls which field the query is sorted by. responses: '200': description: > The response includes a `labels` array containing a page of results (as determined by the `page_size` query parameter). It also includes other useful information, such as the total number of labels that match the query criteria, the number of pages of results, and the URLs of the first, last, next, and previous pages of results. content: application/json: schema: $ref: '#/components/schemas/list_labels_response_body' '400': $ref: '#/components/responses/400_error_response' '500': $ref: '#/components/responses/500_error_response' post: summary: Purchase Label description: Purchase and print a label for shipment tags: - labels operationId: create_label requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/create_label_request_body' responses: '200': description: The requested object creation was a success. content: application/json: schema: $ref: '#/components/schemas/create_label_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/labels/external_shipment_id/{external_shipment_id}': summary: Get Label By External Shipment ID description: Find a label using the external shipment id parameters: - name: external_shipment_id in: path schema: type: string required: true example: 0bcb569d-1727-4ff9-ab49-b2fec0cee5ae get: summary: Get Label By External Shipment ID description: > Find a label by using the external shipment id that was used during label creation tags: - labels operationId: get_label_by_external_shipment_id parameters: - name: label_download_type in: query required: false schema: $ref: '#/components/schemas/label_download_type' example: url responses: '200': description: The requested object creation was a success. content: application/json: schema: $ref: >- #/components/schemas/get_label_by_external_shipment_id_response_body '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/labels/rates/{rate_id}': summary: Use a rate to purchase a label description: >- Purchase a label using a `rate_id` that has been previously generated while looking at various rates for a particular shipment. parameters: - name: rate_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Rate ID post: summary: Purchase Label with Rate ID description: > When retrieving rates for shipments using the `/rates` endpoint, the returned information contains a `rate_id` property that can be used to generate a label without having to refill in the shipment information repeatedly. tags: - labels operationId: create_label_from_rate requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/create_label_from_rate_request_body' responses: '200': description: The requested object creation was a success. content: application/json: schema: $ref: '#/components/schemas/create_label_from_rate_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/labels/shipment/{shipment_id}': summary: Purchase label using shipment ID description: > Purchase a label using a shipment ID that has already been created with the desired address and package info. parameters: - name: shipment_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Shipment ID post: summary: Purchase Label with Shipment ID description: > Purchase a label using a shipment ID that has already been created with the desired address and package info. tags: - labels operationId: create_label_from_shipment requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/create_label_from_shipment_request_body' responses: '200': description: The requested object creation was a success. content: application/json: schema: $ref: '#/components/schemas/create_label_from_shipment_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/labels/{label_id}': summary: Label description: Retrieve information for individual labels. parameters: - name: label_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Label ID get: summary: Get Label By ID description: Retrieve information for individual labels. tags: - labels operationId: get_label_by_id parameters: - name: label_download_type in: query required: false schema: $ref: '#/components/schemas/label_download_type' example: url responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_label_by_id_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/labels/{label_id}/return': summary: Return labels parameters: - name: label_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Label ID post: summary: Create a return label description: Create a return label tags: - labels operationId: create_return_label requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/create_return_label_request_body' responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/create_return_label_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/labels/{label_id}/track': summary: Tracking a Label description: >- Carriers will provide tracking information so the status of your shipment can be monitored parameters: - name: label_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Label ID get: summary: Get Label Tracking Information description: Retrieve the label's tracking information tags: - labels operationId: get_tracking_log_from_label responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_tracking_log_from_label_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/labels/{label_id}/void': summary: Label Voiding description: > Some carriers charge for creating a label upon purchase vs upon use. The Shipengine API allows you to void a label to get a refund. parameters: - name: label_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Label ID put: summary: Void a Label By ID description: Void a label by ID to get a refund. tags: - labels operationId: void_label responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/void_label_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/manifests: summary: Manifests description: > Many manifests are sent electronically to the carrier when you create a label, and often physical manifests are not necessary. Carriers receive the package details, shipping date, and other information that help them plan your package's delivery when you create a label. However, some providers, like USPS require manifests when shipping large numbers of packages. Think about how long it would take for a delivery driver to arrive, pick up 100 packages, and individually scan each of them. A manifest exists so the carrier can scan the manifest and check in all the packages being shipped. get: summary: List Manifests description: >- Similar to querying shipments, we allow you to query manifests since there will likely be a large number over a long period of time. tags: - manifests operationId: list_manifests parameters: - name: warehouse_id in: query required: false schema: $ref: '#/components/schemas/se_id' description: Warehouse ID - name: ship_date_start in: query required: false schema: type: string format: date-time example: '2018-09-23T15:00:00.000Z' description: ship date start range - name: ship_date_end in: query required: false schema: type: string format: date-time example: '2018-09-23T15:00:00.000Z' description: ship date end range - name: created_at_start in: query required: false schema: type: string format: date-time example: '2019-03-12T19:24:13.657Z' description: >- Used to create a filter for when a resource was created (ex. A shipment that was created after a certain time) - name: created_at_end in: query required: false schema: type: string format: date-time example: '2019-03-12T19:24:13.657Z' description: >- Used to create a filter for when a resource was created, (ex. A shipment that was created before a certain time) - name: carrier_id in: query required: false schema: $ref: '#/components/schemas/se_id' description: Carrier ID - name: page in: query required: false schema: type: integer format: int32 minimum: 1 default: 1 example: 2 description: > Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned. - name: page_size in: query required: false schema: type: integer format: int32 minimum: 1 default: 25 example: 50 description: The number of results to return per response. - name: label_ids in: query explode: true required: false schema: type: array items: title: se_id type: string minLength: 1 maxLength: 25 pattern: '^se(-[a-z0-9]+)+$' example: se-28529731 description: >- A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc. description: Array of label ids responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/list_manifests_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' post: summary: Create Manifest description: > Each ShipEngine manifest is created for a specific warehouse, so you'll need to provide the warehouse_id rather than the ship_from address. You can create a warehouse for each location that you want to create manifests for. tags: - manifests operationId: create_manifest requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/create_manifest_request_body' responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/create_manifest_response_body' '400': $ref: '#/components/responses/400_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/manifests/{manifest_id}': summary: Manifest ID description: Manifest ID parameters: - name: manifest_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: The Manifest Id get: summary: Get Manifest By Id description: Get Manifest By Id tags: - manifests operationId: get_manifest_by_id responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_manifest_by_id_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/manifests/requests/{manifest_request_id}': summary: Manifest Request ID description: Manifest Request ID parameters: - name: manifest_request_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: The Manifest Request Id get: summary: Get Manifest Request By Id description: Get Manifest Request By Id tags: - manifests operationId: get_manifest_request_by_id responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/create_manifest_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/packages: summary: Packages description: > Sometimes the default package types that carriers provide aren't enough and you need to create your own. That's where the `/packages` endpoint becomes useful. Create, manage, and delete custom package types to suit your specific needs. get: summary: List Custom Package Types description: List the custom package types associated with the account tags: - package_types operationId: list_package_types responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/list_package_types_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' post: summary: Create Custom Package Type description: >- Create a custom package type to better assist in getting accurate rate estimates tags: - package_types operationId: create_package_type requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/create_package_type_request_body' responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/create_package_type_response_body' '400': $ref: '#/components/responses/400_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/packages/{package_id}': summary: Package description: 'Create, edit, and delete individual custom packages.' parameters: - name: package_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Package ID get: summary: Get Custom Package Type By ID description: Get Custom Package Type by ID tags: - package_types operationId: get_package_type_by_id responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_package_type_by_id_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' put: summary: Update Custom Package Type By ID description: Update the custom package type object by ID tags: - package_types operationId: update_package_type requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/update_package_type_request_body' responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' delete: summary: Delete A Custom Package By ID description: Delete a custom package using the ID tags: - package_types operationId: delete_package_type responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/pickups: summary: Scheduled Pickups description: | Scheduled package pickups get: summary: List Scheduled Pickups description: List all pickups that have been scheduled for this carrier tags: - package_pickups operationId: list_scheduled_pickups parameters: - name: carrier_id in: query required: false schema: $ref: '#/components/schemas/se_id' description: Carrier ID - name: warehouse_id in: query required: false schema: $ref: '#/components/schemas/se_id' description: Warehouse ID - description: >- Only return scheduled pickups that were created on or after a specific date/time name: created_at_start in: query required: false schema: type: string format: date-time example: '2019-03-12T19:24:13.657Z' - description: >- Only return scheduled pickups that were created on or before a specific date/time name: created_at_end in: query required: false schema: type: string format: date-time example: '2019-03-12T19:24:13.657Z' - name: page in: query required: false schema: type: integer format: int32 minimum: 1 default: 1 example: 2 description: > Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned. - name: page_size in: query required: false schema: type: integer format: int32 minimum: 1 default: 25 example: 50 description: The number of results to return per response. responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_pickups_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' post: summary: Schedule a Pickup description: Schedule a package pickup with a carrier tags: - package_pickups operationId: schedule_pickup requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/schedule_pickup_request_body' responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/schedule_pickup_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/pickups/{pickup_id}': summary: Scheduled Pickup description: | A package pickup that has been scheduled with a carrier parameters: - name: pickup_id in: path required: true schema: $ref: '#/components/schemas/pickup_resource_id' get: summary: Get Pickup By ID description: Get Pickup By ID tags: - package_pickups operationId: get_pickup_by_id responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_pickup_by_id_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' delete: summary: Delete a Scheduled Pickup description: Delete a previously-scheduled pickup by ID tags: - package_pickups operationId: delete_scheduled_pickup responses: '200': description: > Return the `pickup_id` of the scheduled pickup that was successfully deleted content: application/json: schema: $ref: '#/components/schemas/delete_pickup_by_id_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/rates: summary: Rates description: Get the various rates for a set of carriers post: summary: Get Shipping Rates description: > It's not uncommon that you want to give your customer the choice between whether they want to ship the fastest, cheapest, or the most trusted route. Most companies don't solely ship things using a single shipping option; so we provide functionality to show you all your options! tags: - rates operationId: calculate_rates requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/calculate_rates_request_body' responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/calculate_rates_response_body' '400': $ref: '#/components/responses/400_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/rates/bulk: summary: Bulk Rates description: Get specific rates for large groups of shipments post: summary: Get Bulk Rates description: Get Bulk Shipment Rates tags: - rates operationId: compare_bulk_rates requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/compare_bulk_rates_request_body' responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/compare_bulk_rates_response_body' '400': $ref: '#/components/responses/400_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/rates/estimate: summary: Rate Estimates description: Show rate estimations between carriers with basic information. post: summary: Estimate Rates description: Get Rate Estimates tags: - rates operationId: estimate_rates requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/estimate_rates_request_body' responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/estimate_rates_response_body' '400': $ref: '#/components/responses/400_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/rates/{rate_id}': summary: Rate description: Get Individual rate information. parameters: - name: rate_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Rate ID get: summary: Get Rate By ID description: Retrieve a previously queried rate by its ID tags: - rates operationId: get_rate_by_id responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_rate_by_id_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/service_points/list: summary: Service Points post: summary: List Service Points description: List carrier service points by location operationId: service_points_list tags: - service_points requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/get_service_points_request' responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/list_service_points_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/service_points/{carrier_code}/{country_code}/{service_point_id}': summary: Service Points parameters: - name: carrier_code in: path required: true schema: type: string minLength: 1 example: stamps_com description: Carrier code - name: country_code in: path required: true schema: type: string minLength: 2 maxLength: 2 example: CA description: > A two-letter [ISO 3166-1 country code](https://en.wikipedia.org/wiki/ISO_3166-1) - name: service_point_id in: path schema: type: string required: true example: '614940' get: summary: Get Service Point By ID description: Returns a carrier service point by using the service_point_id operationId: service_points_get_by_id tags: - service_points responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_service_point_by_id_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/shipments: summary: Shipments description: > Shipments are the gatekeeper to more advanced functionality inside ShipEngine. When you create a shipment, we respond with a shipment_id that is a unique identifier inside of ShipEngine. Additionally, we realize that you may have your own identifier, you can set this by setting the `external_shipment_id` field in the request body. get: summary: List Shipments description: Get list of Shipments tags: - shipments operationId: list_shipments parameters: - name: shipment_status in: query required: false schema: $ref: '#/components/schemas/shipment_status' - name: batch_id in: query required: false schema: $ref: '#/components/schemas/se_id' description: Batch ID - name: tag in: query required: false schema: type: string minLength: 1 example: Letters_to_santa description: >- Search for shipments based on the custom tag added to the shipment object - name: created_at_start in: query required: false schema: type: string format: date-time example: '2019-03-12T19:24:13.657Z' description: >- Used to create a filter for when a resource was created (ex. A shipment that was created after a certain time) - name: created_at_end in: query required: false schema: type: string format: date-time example: '2019-03-12T19:24:13.657Z' description: >- Used to create a filter for when a resource was created, (ex. A shipment that was created before a certain time) - name: modified_at_start in: query required: false schema: type: string format: date-time example: '2019-03-12T19:24:13.657Z' description: >- Used to create a filter for when a resource was modified (ex. A shipment that was modified after a certain time) - name: modified_at_end in: query required: false schema: type: string format: date-time example: '2019-03-12T19:24:13.657Z' description: >- Used to create a filter for when a resource was modified (ex. A shipment that was modified before a certain time) - name: page in: query required: false schema: type: integer format: int32 minimum: 1 default: 1 example: 2 description: > Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned. - name: page_size in: query required: false schema: type: integer format: int32 minimum: 1 default: 25 example: 50 description: The number of results to return per response. - name: sales_order_id in: query required: false schema: type: string description: Sales Order ID - name: sort_dir in: query required: false schema: allOf: - $ref: '#/components/schemas/sort_dir' default: desc description: Controls the sort order of the query. - name: sort_by in: query required: false schema: $ref: '#/components/schemas/shipments_sort_by' example: modified_at responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/list_shipments_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' post: summary: Create Shipments description: Create one or multiple shipments. tags: - shipments operationId: create_shipments requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/create_shipments_request_body' responses: '200': description: The requested object creation was a success. content: application/json: schema: $ref: '#/components/schemas/create_shipments_response_body' '400': $ref: '#/components/responses/400_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/shipments/external_shipment_id/{external_shipment_id}': summary: External Shipment ID description: > When a shipment object is created with a custom shipment ID, you can query it using this endpoint parameters: - name: external_shipment_id in: path schema: type: string required: true example: 0bcb569d-1727-4ff9-ab49-b2fec0cee5ae get: summary: Get Shipment By External ID description: >- Query Shipments created using your own custom ID convention using this endpint tags: - shipments operationId: get_shipment_by_external_id responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_shipment_by_external_id_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/shipments/recognize: summary: Parse shipping info description: > Data often enters your system as unstructured text (for example: emails, SMS messages, support tickets, or other documents). ShipEngine's shipment-recognition API helps you extract meaningful shipping data (people's names, addresses, package weights and dimensions, insurance and delivery requirements, etc.) from this unstructured text. put: summary: Parse shipping info description: > The shipment-recognition API makes it easy for you to extract shipping data from unstructured text, including people's names, addresses, package weights and dimensions, insurance and delivery requirements, and more. Data often enters your system as unstructured text (for example: emails, SMS messages, support tickets, or other documents). ShipEngine's shipment-recognition API helps you extract meaningful, structured data from this unstructured text. The parsed shipment data is returned in the same structure that's used for other ShipEngine APIs, so you can easily use the parsed data to create a shipping label. > **Note:** Shipment recognition is currently supported for the United States, Canada, Australia, New Zealand, the United Kingdom, and Ireland. tags: - shipments operationId: parse_shipment requestBody: required: true description: > The only required field is `text`, which is the text to be parsed. You can optionally also provide a `shipment` containing any already-known values. For example, you probably already know the `ship_from` address, and you may also already know what carrier and service you want to use. content: application/json: schema: $ref: '#/components/schemas/parse_shipment_request_body' examples: text_only: summary: Text only description: > This is the simplest way to call the shipment-recognition API. Just pass the text to be parsed and nothing else. value: text: > I have a 4oz package that's 5x10x14in, and I need to ship it to Margie McMiller at 3800 North Lamar suite 200 in austin, tx 78652. Please send it via USPS first class and require an adult signature. It also needs to be insured for $400. some_known_fields: summary: Some known fields description: > You can optionally provide a `shipment` object containing any already-known values. For example, you probably already know the `ship_from` address, and you may also already know what carrier and service you want to use. value: text: > I have a 4oz package that's 5x10x14in, and I need to ship it to Margie McMiller at 3800 North Lamar suite 200 in austin, tx 78652. Please send it via USPS first class and require an adult signature. It also needs to be insured for $400. shipment: service_code: usps_first_class_mail ship_from: company_name: My Awesome Store phone: 555-555-5555 address_line1: 587 Shotwell St. address_line2: Suite 201 city_locality: San Francisco state_province: CA postal_code: 94110 country_code: US address_residential_indicator: 'yes' responses: '200': description: > Returns the parsed shipment, as well as a confidence score and a list of all the shipping entities that were recognized in the text. content: application/json: schema: $ref: '#/components/schemas/parse_shipment_response_body' examples: text_only: description: > This response shows that the shipment-recognition API was able to recognize all the shipping entities in the text. Notice that the `ship_from` field is not populated, since it wasn't included in the request or in the parsed text. value: score: 0.9031369611169101 shipment: carrier_id: se-118608 service_code: usps_first_class_mail confirmation: adult_signature ship_to: name: Margie McMiller company_name: Adult Signature address_line1: 3800 North Lamar address_line2: Suite 200 city_locality: Austin state_province: TX postal_code: 78652 address_residential_indicator: unknown packages: - weight: value: 4 unit: ounce dimensions: length: 5 width: 10 height: 14 unit: inch insured_value: amount: 400 currency: USD entities: - type: weight score: 0.9805313966503588 text: 4oz start_index: 9 end_index: 11 result: value: 4 unit: ounce - type: dimensions score: 1 text: 5x10x14in start_index: 28 end_index: 36 result: length: 5 width: 10 height: 14 unit: inch - type: dimension score: 0.9805313966503588 text: 14in start_index: 33 end_index: 36 result: unit: inch value: 14 - type: address score: 0.9281558837267101 text: >- to Margie McMiller at 3800 North Lamar suite 200 in austin, tx 78652. Please send it via USPS first class and require an adult signature start_index: 61 end_index: 196 result: direction: to name: Margie McMiller company_name: Adult Signature address_line1: 3800 North Lamar address_line2: Suite 200 city_locality: Austin state_province: TX postal_code: 78652 - type: person score: 0.9519646137063122 text: Margie McMiller start_index: 64 end_index: 78 result: value: Margie McMiller - type: address_line score: 0.9805313966503588 text: 3800 North Lamar start_index: 83 end_index: 98 result: line: 1 value: 3800 North Lamar - type: number score: 0.9805313966503588 text: 3800 start_index: 83 end_index: 86 result: type: cardinal value: 3800 - type: address_line score: 1 text: suite 200 start_index: 100 end_index: 108 result: line: 2 value: Suite 200 - type: dimension score: 0.4792571878834418 text: 200 in start_index: 106 end_index: 111 result: unit: inch value: 200 - type: city_locality score: 0.9805313966503588 text: austin start_index: 113 end_index: 118 result: value: Austin - type: state_province score: 0.6082904353940255 text: tx start_index: 121 end_index: 122 result: name: Texas value: TX - type: postal_code score: 0.9519646137063122 text: 78652 start_index: 124 end_index: 128 result: value: 78652 - type: carrier score: 0.9519646137063122 text: USPS start_index: 150 end_index: 153 result: name: Stamps.com value: se-118608 - type: service score: 0.6082904353940255 text: first class start_index: 155 end_index: 165 result: name: USPS First Class Mail value: usps_first_class_mail - type: number score: 0.9805313966503588 text: first start_index: 155 end_index: 159 result: type: ordinal value: 1 - type: company score: 0.9519646137063122 text: adult signature start_index: 182 end_index: 196 result: value: Adult Signature - type: delivery_confirmation score: 0.8530163983409642 text: adult signature start_index: 182 end_index: 196 result: name: Adult Signature value: adult_signature - type: insurance score: 0.8530163983409642 text: insured for $400 start_index: 219 end_index: 234 result: value: 400 unit: USD - type: insured_value score: 1 text: $400 start_index: 231 end_index: 234 result: unit: USD value: 400 some_known_fields: description: > This response is shows that the shipment-recognition API was able to recognize all the shipping entities in the text. Notice that the `ship_from` and `service_code` fields are populated with the values that were provided in the request. value: score: 0.9031369611169101 shipment: carrier_id: se-118608 service_code: usps_first_class_mail confirmation: adult_signature ship_to: name: Margie McMiller company_name: Adult Signature address_line1: 3800 North Lamar address_line2: Suite 200 city_locality: Austin state_province: TX postal_code: 78652 address_residential_indicator: unknown ship_from: company_name: My Awesome Store phone: 555-555-5555 address_line1: 587 Shotwell St. address_line2: Suite 201 city_locality: San Francisco state_province: CA postal_code: 94110 country_code: US address_residential_indicator: 'yes' packages: - weight: value: 4 unit: ounce dimensions: length: 5 width: 10 height: 14 unit: inch insured_value: amount: 400 currency: USD entities: - type: weight score: 0.9805313966503588 text: 4oz start_index: 9 end_index: 11 result: value: 4 unit: ounce - type: dimensions score: 1 text: 5x10x14in start_index: 28 end_index: 36 result: length: 5 width: 10 height: 14 unit: inch - type: dimension score: 0.9805313966503588 text: 14in start_index: 33 end_index: 36 result: unit: inch value: 14 - type: address score: 0.9281558837267101 text: >- to Margie McMiller at 3800 North Lamar suite 200 in austin, tx 78652. Please send it via USPS first class and require an adult signature start_index: 61 end_index: 196 result: direction: to name: Margie McMiller company_name: Adult Signature address_line1: 3800 North Lamar address_line2: Suite 200 city_locality: Austin state_province: TX postal_code: 78652 - type: person score: 0.9519646137063122 text: Margie McMiller start_index: 64 end_index: 78 result: value: Margie McMiller - type: address_line score: 0.9805313966503588 text: 3800 North Lamar start_index: 83 end_index: 98 result: line: 1 value: 3800 North Lamar - type: number score: 0.9805313966503588 text: 3800 start_index: 83 end_index: 86 result: type: cardinal value: 3800 - type: address_line score: 1 text: suite 200 start_index: 100 end_index: 108 result: line: 2 value: Suite 200 - type: dimension score: 0.4792571878834418 text: 200 in start_index: 106 end_index: 111 result: unit: inch value: 200 - type: city_locality score: 0.9805313966503588 text: austin start_index: 113 end_index: 118 result: value: Austin - type: state_province score: 0.6082904353940255 text: tx start_index: 121 end_index: 122 result: name: Texas value: TX - type: postal_code score: 0.9519646137063122 text: 78652 start_index: 124 end_index: 128 result: value: 78652 - type: carrier score: 0.9519646137063122 text: USPS start_index: 150 end_index: 153 result: name: Stamps.com value: se-118608 - type: service score: 0.6082904353940255 text: first class start_index: 155 end_index: 165 result: name: USPS First Class Mail value: usps_first_class_mail - type: number score: 0.9805313966503588 text: first start_index: 155 end_index: 159 result: type: ordinal value: 1 - type: company score: 0.9519646137063122 text: adult signature start_index: 182 end_index: 196 result: value: Adult Signature - type: delivery_confirmation score: 0.8530163983409642 text: adult signature start_index: 182 end_index: 196 result: name: Adult Signature value: adult_signature - type: insurance score: 0.8530163983409642 text: insured for $400 start_index: 219 end_index: 234 result: value: 400 unit: USD - type: insured_value score: 1 text: $400 start_index: 231 end_index: 234 result: unit: USD value: 400 '400': $ref: '#/components/responses/400_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/shipments/{shipment_id}': summary: Get and Update Shipment description: Retrieve and Update and individual shipment based on its ID parameters: - name: shipment_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Shipment ID get: summary: Get Shipment By ID description: Get an individual shipment based on its ID tags: - shipments operationId: get_shipment_by_id responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_shipment_by_id_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' put: summary: Update Shipment By ID description: Update a shipment object based on its ID tags: - shipments operationId: update_shipment requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/update_shipment_request_body' responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/update_shipment_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/shipments/{shipment_id}/cancel': summary: Cancel Shipment description: Cancel a Shipment parameters: - name: shipment_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Shipment ID put: summary: Cancel a Shipment description: > Mark a shipment cancelled, if it is no longer needed or being used by your organized. Any label associated with the shipment needs to be voided first An example use case would be if a batch label creation job is going to run at a set time and only queries `pending` shipments. Marking a shipment as cancelled would remove it from this process tags: - shipments operationId: cancel_shipments responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/shipments/{shipment_id}/rates': summary: Shipment Rates description: > Once a shipment is complete with the desired shipping information, you can then search for rates available based on the carriers associated with your account parameters: - name: shipment_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Shipment ID get: summary: Get Shipment Rates description: Get Rates for the shipment information associated with the shipment ID tags: - shipments operationId: list_shipment_rates parameters: - name: created_at_start in: query required: false schema: type: string format: date-time example: '2019-03-12T19:24:13.657Z' description: >- Used to create a filter for when a resource was created (ex. A shipment that was created after a certain time) responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/list_shipment_rates_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/shipments/tags: summary: Shipment Tags description: > Tags associated with the shipment object to be used to organize and query shipment items. put: summary: Update Shipments Tags description: Update Shipments Tags tags: - shipments operationId: shipments_update_tags parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/update_shipments_tags_request_body' required: true responses: '204': description: NoContent '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/shipments/{shipment_id}/tags': summary: Shipment Tags description: > Tags associated with the shipment object to be used to organize and query shipment items. parameters: - name: shipment_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Shipment ID get: summary: Get Shipment Tags description: Get Shipment tags based on its ID tags: - shipments operationId: shipments_list_tags responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/tag_shipment_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/shipments/{shipment_id}/tags/{tag_name}': summary: Shipment Tags description: > Tags associated with the shipment object to be used to organize and query shipment items. parameters: - name: shipment_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Shipment ID - name: tag_name in: path required: true schema: $ref: '#/components/schemas/tag_name' post: summary: Add Tag to Shipment description: Add a tag to the shipment object tags: - shipments operationId: tag_shipment responses: '200': description: The requested object creation was a success. content: application/json: schema: $ref: '#/components/schemas/tag_shipment_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' delete: summary: Remove Tag from Shipment description: Remove an existing tag from the Shipment object tags: - shipments operationId: untag_shipment responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/tags: summary: Tags description: > Tags are simple text-based flags or identifiers. Tags can be used as a simple label, such as Guaranteed_Overnight or Fragile so shipments can be easily [queried later](https://www.shipengine.com/docs/reference/list-shipments/). get: summary: Get Tags description: Get a list of all tags associated with an account. tags: - tags operationId: list_tags responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/list_tags_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/tags/{tag_name}': summary: Tag description: Create and delete tags parameters: - name: tag_name in: path required: true schema: $ref: '#/components/schemas/tag_name' post: summary: Create a New Tag description: Create a new Tag for customizing how you track your shipments tags: - tags operationId: create_tag responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/create_tag_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' delete: summary: Delete Tag description: Delete a tag that is no longer needed tags: - tags operationId: delete_tag responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/tags/{tag_name}/{new_tag_name}': summary: Tag description: Update tag name parameters: - name: tag_name in: path required: true schema: $ref: '#/components/schemas/tag_name' - name: new_tag_name in: path required: true schema: $ref: '#/components/schemas/tag_name' put: summary: Update Tag Name description: >- Change a tag name while still keeping the relevant shipments attached to it tags: - tags operationId: rename_tag responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/tokens/ephemeral: post: summary: Get Ephemeral Token description: >- This endpoint returns a token that can be passed to an application for authorized access. The lifetime of this token is 10 seconds. operationId: tokens_get_ephemeral_token parameters: - name: redirect in: query required: false schema: $ref: '#/components/schemas/redirect' description: >- Include a redirect url to the application formatted with the ephemeral token. tags: - tokens responses: '200': description: OK content: application/json: schema: $ref: >- #/components/schemas/tokens_get_ephemeral_token_response_body.yaml /v1/tracking: summary: Tracking a Package description: >- If you generate your labels through ShipEngine, then you can subscribe to real-time tracking events for free! get: summary: Get Tracking Information description: Retrieve package tracking information tags: - tracking operationId: get_tracking_log parameters: - name: carrier_code in: query required: false schema: type: string minLength: 1 example: stamps_com description: > A [shipping carrier](https://www.shipengine.com/docs/carriers/setup/), such as `fedex`, `dhl_express`, `stamps_com`, etc. - name: tracking_number in: query required: false schema: type: string minLength: 1 example: '9405511899223197428490' description: The tracking number associated with a shipment responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_tracking_log_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/tracking/start: summary: Start Tracking a Package description: > Allows you to subscribe to tracking updates for a package. You specify the carrier_code and tracking_number of the package, and receive notifications via webhooks whenever the shipping status changes. post: summary: Start Tracking a Package description: > Allows you to subscribe to tracking updates for a package. You specify the carrier_code and tracking_number of the package, and receive notifications via webhooks whenever the shipping status changes. tags: - tracking operationId: start_tracking parameters: - name: carrier_code in: query required: false schema: type: string minLength: 1 example: stamps_com description: > A [shipping carrier](https://www.shipengine.com/docs/carriers/setup/), such as `fedex`, `dhl_express`, `stamps_com`, etc. - name: tracking_number in: query required: false schema: type: string minLength: 1 example: '9405511899223197428490' description: The tracking number associated with a shipment responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/tracking/stop: summary: Stop Tracking a Package description: Unsubscribe from tracking updates for a package. post: summary: Stop Tracking a Package description: Unsubscribe from tracking updates for a package. tags: - tracking operationId: stop_tracking parameters: - name: carrier_code in: query required: false schema: type: string minLength: 1 example: stamps_com description: > A [shipping carrier](https://www.shipengine.com/docs/carriers/setup/), such as `fedex`, `dhl_express`, `stamps_com`, etc. - name: tracking_number in: query required: false schema: type: string minLength: 1 example: '9405511899223197428490' description: The tracking number associated with a shipment responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' /v1/warehouses: summary: Warehouses description: > You likely have one or more warehouse locations that you frequently ship from, in which case it would be annoying to have to specify the ship_from and return_to addresses on every shipment. The solution is to [Create a Warehouse](https://www.shipengine.com/docs/reference/create-warehouse/), then you can simply pass the warehouse_id instead. get: summary: List Warehouses description: Retrieve a list of warehouses associated with this account. tags: - warehouses operationId: list_warehouses responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/list_warehouses_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' post: summary: Create Warehouse description: > Create a warehouse location that you can use to create shipping items by simply passing in the generated warehouse id. If the return address is not supplied in the request body then it is assumed that the origin address is the return address as well tags: - warehouses operationId: create_warehouse requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/create_warehouse_request_body' responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/create_warehouse_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/warehouses/{warehouse_id}': summary: Warehouse description: > You likely have one or more warehouse locations that you frequently ship from, in which case it would be annoying to have to specify the ship_from and return_to addresses on every shipment. The solution is to [Create a Warehouse](https://www.shipengine.com/docs/reference/create-warehouse/), then you can simply pass the warehouse_id instead. parameters: - name: warehouse_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Warehouse ID get: summary: Get Warehouse By Id description: Retrieve warehouse data based on the warehouse ID tags: - warehouses operationId: get_warehouse_by_id responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/get_warehouse_by_id_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' put: summary: Update Warehouse By Id description: Update Warehouse object information tags: - warehouses operationId: update_warehouse requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/update_warehouse_request_body' responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' delete: summary: Delete Warehouse By ID description: Delete a warehouse by ID tags: - warehouses operationId: delete_warehouse responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' '/v1/warehouses/{warehouse_id}/settings': summary: Warehouse settings description: Warehouse settings parameters: - name: warehouse_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Warehouse ID put: summary: Update Warehouse Settings description: Update Warehouse settings object information tags: - warehouses operationId: update_warehouse_settings requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/update_warehouse_settings_request_body' responses: '204': description: The request was successful. content: text/plain: schema: $ref: '#/components/schemas/empty_response_body' application/json: schema: $ref: '#/components/schemas/empty_response_body' '400': $ref: '#/components/responses/400_error_response' '404': $ref: '#/components/responses/404_error_response' '500': $ref: '#/components/responses/500_error_response' servers: - url: 'https://api.shipengine.com' components: schemas: get_account_settings_response_body: title: get_account_settings_response_body allOf: - $ref: '#/components/schemas/list_account_settings_body' list_account_settings_body: title: list_account_settings_body type: object description: An account settings list response body additionalProperties: false allOf: - $ref: '#/components/schemas/account_settings' account_settings: title: account_settings type: object description: A ShipEngine account settings response body additionalProperties: false properties: default_label_layout: allOf: - $ref: '#/components/schemas/default_label_layout' default_label_layout: title: default_label_layout type: string enum: - 4x6 - Letter description: The possible default label layout values error_response_body: title: error_response_body type: object description: An error response body required: - request_id - errors additionalProperties: false properties: request_id: allOf: - $ref: '#/components/schemas/uuid' description: > A UUID that uniquely identifies the request id. This can be given to the support team to help debug non-trivial issues that may occur errors: type: array readOnly: true items: allOf: - $ref: '#/components/schemas/error' description: The errors associated with the failed API call uuid: title: uuid type: string format: uuid minLength: 36 maxLength: 36 pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ example: aa3d8e8e-462b-4476-9618-72db7f7b7009 description: A UUID (a.k.a. GUID) that uniquely identifies a resource error: title: error type: object description: | The error structure that gets returned with almost all failed API calls required: - error_source - error_type - error_code - message additionalProperties: false properties: error_source: allOf: - $ref: '#/components/schemas/error_source' error_type: allOf: - $ref: '#/components/schemas/error_type' error_code: allOf: - $ref: '#/components/schemas/error_code' message: type: string readOnly: true example: Body of request cannot be null. minLength: 1 description: An error message associated with the failed API call error_source: title: error_source type: string enum: - carrier - order_source - shipengine description: > The source of the error, as indicated by the name this informs us if the API call failed because of the carrier, the order source, or the ShipEngine API itself. error_type: title: error_type type: string enum: - account_status - business_rules - validation - security - system - integrations description: | The type of error error_code: title: error_code type: string enum: - auto_fund_not_supported - batch_cannot_be_modified - carrier_conflict - carrier_disconnected - carrier_not_connected - carrier_not_supported - confirmation_not_supported - default_warehouse_cannot_be_deleted - field_conflict - field_value_required - forbidden - identifier_conflict - identifiers_must_match - insufficient_funds - invalid_address - invalid_billing_plan - invalid_field_value - invalid_identifier - invalid_status - invalid_string_length - label_images_not_supported - meter_failure - order_source_not_active - rate_limit_exceeded - refresh_not_supported - request_body_required - return_label_not_supported - settings_not_supported - subscription_inactive - terms_not_accepted - tracking_not_supported - trial_expired - unauthorized - unknown - unspecified - verification_failure - warehouse_conflict - webhook_event_type_conflict - customs_items_required - incompatible_paired_labels - invalid_charge_event - invalid_object - no_rates_returned description: The error code specified for the failed API Call list_account_settings_images_response_body: title: list_account_settings_images_response_body allOf: - $ref: '#/components/schemas/list_account_images_response_body' list_account_images_response_body: title: list_account_images_response_body type: object description: A list account images response body required: - images additionalProperties: false properties: images: type: array readOnly: true minItems: 0 items: allOf: - title: account_settings_images type: object description: A ShipEngine account images body additionalProperties: false properties: label_image_id: readOnly: true allOf: - $ref: '#/components/schemas/image_id' description: > A string that uniquely identifies the image. This ID is generated by ShipEngine when the image is uploaded. name: type: string minLength: 1 maxLength: 50 example: My logo description: | A human readable name for the image. is_default: type: boolean example: false description: | Indicates whether this image is set as default. image_content_type: allOf: - type: string enum: - image/png - image/jpeg description: The image type description: | The file type of the image. image_data: type: string example: >- iVBORw0KGgoAAAANSUhEUgAAABkAAAAZCAYAAADE6YVjAAAAAXNSR0IArs4c6QAAAiVJREFUSEu91j3IeVEcB/CvSTIoBrFSikEZMdjsjExeUspgUEp5SUpeshrIgEFJJmWwMZHJQGHDhJSXTPfpnH/8ebzd56HnN93u7ZzP/f1+55x7Ob1ejxEKheByufh0HI9HrFYrcKbTKUMu5HI5BALBx5zNZoPxeAySAGc2mzF8Pp/e+BR0Ash8u93uHyKVSnH54J2Mvs8zn8//I6RO70L3xt8g70CPXvAu8hvoWQUeIj+BXpX4KcIGegWQOV4izyA2AGvkHsQW+BFyCUkkEiwWC9Ybl1W5Ls8ZMoAABCIbmE3cINFoFMFgEEajEeVyGSKRCJ1OB3q9ns5nMpmQTCaxXq9/l8loNEKj0YDX66UACYvFQq9brRYcDgdUKhU9RD/SEwLm83lEIhGUSiX0+33E4/GrU5otRMs1mUyYbDYLu90OhUJBMzhlZbPZ4Pf7odFo4HQ6b1rABqJIvV5nttstLc0pSIn2+z0tTy6XQ6FQoI/a7TZ0Ot0V9gqiiMFgYKrVKm0yieVyCZ/PB6vVSpF0Ok2zJHEqIY/HYw1RxOfzMYlE4jwoEAhAJpPBbDZf9eBwOCCVSsHtdp9f6FJ6egorlUqmVqvRfjSbTXS7XXg8nptP8Svk0RF01ROtVguSUTgchlgsPpeOZBaLxTAcDlEsFpHJZPC9XM8yoshgMGBCoRBdQWTCU7hcLjohWb5kM6rValQqlfMKfLbbb77xf/K38hf/XV9ilOpnLqvnogAAAABJRU5ErkJggg== description: | A base64 encoded string representation of the image. created_at: readOnly: true allOf: - $ref: '#/components/schemas/date_time' description: >- The date and time that the image was created in ShipEngine. modified_at: readOnly: true allOf: - $ref: '#/components/schemas/date_time' description: >- The date and time that the image was modified in ShipEngine. description: Image description: Image List allOf: - $ref: '#/components/schemas/paged_list_response_body' paged_list_response_body: title: paged_list_response_body type: object required: - total - page - pages - links additionalProperties: true properties: total: type: integer minimum: 0 example: 2750 description: The total number of items across all pages of results page: type: integer minimum: 1 example: 1 description: >- The current page number of results. For example, if there are 80 results, and the page size is 25, then `page` could be 1, 2, 3, or 4. The first three pages would contain 25 items each, and the fourth page would contain the five remaining items. pages: type: integer minimum: 0 example: 4 description: >- The total number of pages of results. For example, if there are 80 results, and the page size is 25, then `pages` would be 4. The first three pages would contain 25 items each, and the fourth page would contain the five remaining items. If there are no results, then `pages` will be zero. links: allOf: - $ref: '#/components/schemas/pagination_link' description: > Many ShipEngine endpoints return a paged list of items. In addition to the returned items, these responses also include information about the total number of items, the number of pages of results, and URLs of other pages of results. pagination_link: title: pagination_link type: object description: Helpful links to other pages of results required: - first - last - prev - next additionalProperties: false properties: first: allOf: - $ref: '#/components/schemas/link' description: > The link to the first page of results. This object will _always_ have an `href` field. If there are no results, then the first page will contain an empty array of items. last: allOf: - $ref: '#/components/schemas/link' description: > The link to the final page of results. This object will _always_ have an `href` field. If there are no results, then the final page will contain an empty array of items. prev: allOf: - $ref: '#/components/schemas/optional_link' description: > The link to the previous page of results. The `href` field will only be set when the `page` is 2 or greater. next: allOf: - $ref: '#/components/schemas/optional_link' description: > The link to the next page of results. The `href` field will only be set when the `page` is less than `pages`. link: title: link type: object description: A link to a related resource additionalProperties: false required: - href allOf: - $ref: '#/components/schemas/optional_link' optional_link: title: optional_link type: object description: >- A link to a related resource, or an empty object if there is no resource to link to additionalProperties: false properties: href: allOf: - $ref: '#/components/schemas/url' description: 'The URL of the linked resource, if any' type: type: string minLength: 1 description: >- The type of resource, or the type of relationship to the parent resource url: title: url type: string format: url minLength: 1 example: 'http://api.shipengine.com/v1/labels/se-28529731' description: A URL create_account_settings_image_request_body: title: create_account_settings_image_request_body type: object description: A ShipEngine account settings images request body required: - name - image_content_type - image_data additionalProperties: false allOf: - $ref: '#/components/schemas/account_settings_images' account_settings_images: title: account_settings_images type: object description: A ShipEngine account images body additionalProperties: false properties: label_image_id: readOnly: true allOf: - $ref: '#/components/schemas/image_id' description: > A string that uniquely identifies the image. This ID is generated by ShipEngine when the image is uploaded. name: type: string minLength: 1 maxLength: 50 example: My logo description: | A human readable name for the image. is_default: type: boolean example: false description: | Indicates whether this image is set as default. image_content_type: allOf: - type: string enum: - image/png - image/jpeg description: The image type description: | The file type of the image. image_data: type: string example: >- iVBORw0KGgoAAAANSUhEUgAAABkAAAAZCAYAAADE6YVjAAAAAXNSR0IArs4c6QAAAiVJREFUSEu91j3IeVEcB/CvSTIoBrFSikEZMdjsjExeUspgUEp5SUpeshrIgEFJJmWwMZHJQGHDhJSXTPfpnH/8ebzd56HnN93u7ZzP/f1+55x7Ob1ejxEKheByufh0HI9HrFYrcKbTKUMu5HI5BALBx5zNZoPxeAySAGc2mzF8Pp/e+BR0Ash8u93uHyKVSnH54J2Mvs8zn8//I6RO70L3xt8g70CPXvAu8hvoWQUeIj+BXpX4KcIGegWQOV4izyA2AGvkHsQW+BFyCUkkEiwWC9Ybl1W5Ls8ZMoAABCIbmE3cINFoFMFgEEajEeVyGSKRCJ1OB3q9ns5nMpmQTCaxXq9/l8loNEKj0YDX66UACYvFQq9brRYcDgdUKhU9RD/SEwLm83lEIhGUSiX0+33E4/GrU5otRMs1mUyYbDYLu90OhUJBMzhlZbPZ4Pf7odFo4HQ6b1rABqJIvV5nttstLc0pSIn2+z0tTy6XQ6FQoI/a7TZ0Ot0V9gqiiMFgYKrVKm0yieVyCZ/PB6vVSpF0Ok2zJHEqIY/HYw1RxOfzMYlE4jwoEAhAJpPBbDZf9eBwOCCVSsHtdp9f6FJ6egorlUqmVqvRfjSbTXS7XXg8nptP8Svk0RF01ROtVguSUTgchlgsPpeOZBaLxTAcDlEsFpHJZPC9XM8yoshgMGBCoRBdQWTCU7hcLjohWb5kM6rValQqlfMKfLbbb77xf/K38hf/XV9ilOpnLqvnogAAAABJRU5ErkJggg== description: | A base64 encoded string representation of the image. created_at: readOnly: true allOf: - $ref: '#/components/schemas/date_time' description: The date and time that the image was created in ShipEngine. modified_at: readOnly: true allOf: - $ref: '#/components/schemas/date_time' description: The date and time that the image was modified in ShipEngine. image_id: title: image_id type: string minLength: 4 example: img_DtBXupDBxREpHnwEXhTfgK description: Used to identify an image resource. date_time: title: date_time type: string format: date-time pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[-+]\d{2}:\d{2})$' example: '2018-09-23T15:00:00.000Z' description: > An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that represents a date and time. get_account_settings_images_response_body: title: get_account_settings_images_response_body type: object description: A get account images by id response body additionalProperties: false allOf: - $ref: '#/components/schemas/account_settings_images' empty_response_body: title: empty_response_body type: string minLength: 0 maxLength: 0 update_account_settings_image_request_body: title: update_account_settings_image_request_body type: object description: A ShipEngine account settings images request body required: - is_default additionalProperties: false allOf: - $ref: '#/components/schemas/account_settings_images' parse_address_request_body: title: parse_address_request_body type: object description: > The only required field is `text`, which is the text to be parsed. You can optionally also provide an `address` containing already-known values. For example, you may already know the recipient's name, city, and country, and only want to parse the street address into separate lines. required: - text additionalProperties: false properties: text: type: string minLength: 1 example: >- Margie McMiller at 3800 North Lamar suite 200 in austin, tx. The zip code there is 78652. description: The unstructured text that contains address-related entities address: allOf: - $ref: '#/components/schemas/partial_address' description: > You can optionally provide any already-known address values. For example, you may already know the recipient's name, city, and country, and only want to parse the street address into separate lines. partial_address: title: partial_address type: object description: A complete or partial mailing address. additionalProperties: false properties: name: type: string minLength: 1 example: John Doe description: > The name of a contact person at this address. This field may be set instead of - or in addition to - the `company_name` field. phone: type: string minLength: 1 example: +1 204-253-9411 ext. 123 description: > The phone number of a contact person at this address. The format of this phone number varies depending on the country. email: type: string nullable: true example: example@example.com description: | Email for the address owner. company_name: type: string minLength: 1 nullable: true example: The Home Depot description: > If this is a business address, then the company name should be specified here. address_line1: type: string minLength: 1 example: 1999 Bishop Grandin Blvd. description: > The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines. address_line2: type: string minLength: 1 nullable: true example: Unit 408 description: > The second line of the street address. For some addresses, this line may not be needed. address_line3: type: string minLength: 1 nullable: true example: 'Building #7' description: > The third line of the street address. For some addresses, this line may not be needed. city_locality: type: string minLength: 1 example: Winnipeg description: The name of the city or locality state_province: type: string minLength: 1 example: Manitoba description: > The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation. postal_code: allOf: - $ref: '#/components/schemas/postal_code' country_code: allOf: - $ref: '#/components/schemas/country_code' description: > The two-letter [ISO 3166-1 country code](https://en.wikipedia.org/wiki/ISO_3166-1) address_residential_indicator: default: unknown example: 'no' description: Indicates whether this is a residential address. allOf: - $ref: '#/components/schemas/address_residential_indicator' postal_code: title: postal_code minLength: 1 type: string example: 78756-3717 description: postal code country_code: title: country_code type: string minLength: 2 maxLength: 2 example: CA description: > A two-letter [ISO 3166-1 country code](https://en.wikipedia.org/wiki/ISO_3166-1) address_residential_indicator: title: address_residential_indicator type: string enum: - unknown - 'yes' - 'no' description: Indicates whether an address is residential. parse_address_response_body: title: parse_address_response_body type: object description: > The parsed address, as well as a confidence score and a list of all the entities that were recognized in the text. required: - score - address - entities additionalProperties: false properties: score: type: number format: double minimum: 0 maximum: 1 description: > A confidence score between zero and one that indicates how certain the API is that it understood the text. address: allOf: - $ref: '#/components/schemas/partial_address' description: > The parsed address. This address may not be complete, depending on how much information was included in the text and how confident the API is about each recognized entity. > **Note:** The address-recognition API does not currently perform any validation of the parsed address, so we recommend that you use the [address-validation API](https://www.shipengine.com/docs/addresses/validation/) to ensure that the address is correct. entities: type: array minItems: 0 items: $ref: '#/components/schemas/recognized_entity' description: > All of the entities that were recognized in the text. An "entity" is a single piece of data, such as a city, a postal code, or an address line. Each entity includes the original text and the parsed value. recognized_entity: title: recognized_entity type: object description: > An entity is a single piece of data that was recognized in unstructured text. For example, a city, a postal code, package dimensions, insured value, etc. Each entity includes the original text and the parsed value. required: - type - score - text - start_index - end_index additionalProperties: false properties: type: type: string minLength: 1 description: 'The Entity type (e.g. "weight", "person", "address_line1", etc.)' score: format: double minimum: 0 maximum: 1 type: number description: > A confidence score between zero and one that indicates how certain the API is that it correctly recognized this entity text: type: string minLength: 1 description: >- The substring from the original text that was recognized as this entity start_index: type: integer minimum: 0 description: >- The index of the first character of this entity within the original text end_index: type: integer minimum: 0 description: >- The index of the last character of this entity within the original text result: $ref: '#/components/schemas/normalized_entity' normalized_entity: title: normalized_entity type: object additionalProperties: true properties: {} description: > The normalized value of the entity. Most entity results have a `value` field, which is the normalized value of the entity. For example, if the substring "john doe" was recognized as a "person" entity, then the value might be normalized to have proper capitalization (e.g. "John Doe"). Or if the substring "ft worth" was recognized as a "city" entity, then the value might be normalized to "Fort Worth". Some entities have other information in addition to, or instead of a `value`. For example, a "dimensions" entity will have separate fields for `length`, `width`, `height`, and `unit`. validate_address_request_body: title: validate_address_request_body type: array description: An address validation request body items: allOf: - $ref: '#/components/schemas/address_to_validate' description: An array of addresses to validate. address_to_validate: title: address_to_validate type: object description: | Any residential or business mailing address, anywhere in the world. required: - address_line1 - city_locality - state_province - country_code additionalProperties: false allOf: - $ref: '#/components/schemas/partial_address' validate_address_response_body: title: validate_address_response_body type: array description: An address validation response body items: readOnly: true allOf: - $ref: '#/components/schemas/address_validation_result' description: The address validation response body address_validation_result: title: address_validation_result type: object description: An address validation result required: - status - original_address - matched_address - messages additionalProperties: false properties: status: allOf: - $ref: '#/components/schemas/address_validation_status' original_address: allOf: - $ref: '#/components/schemas/address' description: The original address that was sent for validation matched_address: nullable: true readOnly: true allOf: - $ref: '#/components/schemas/address' description: The matched address found by the Shipengine API messages: type: array readOnly: true default: [] items: $ref: '#/components/schemas/response_message' description: >- The list of messages that were generated during the address validation request. address_validation_status: title: address_validation_status type: string enum: - unverified - verified - warning - error description: The possible address validation status values address: title: address type: object description: > Any residential or business mailing address, anywhere in the world. > **Note:** Either `name` or `company_name` must be set. Both may be specified, if relevant. required: - name - phone - address_line1 - city_locality - state_province - postal_code - country_code - address_residential_indicator additionalProperties: false allOf: - $ref: '#/components/schemas/partial_address' response_message: title: response_message type: object description: >- A response message that displays when additional info is needed for an address validation request. additionalProperties: false required: - code - message - type - detail_code properties: code: readOnly: true allOf: - $ref: '#/components/schemas/address_validation_code' message: type: string readOnly: true example: Invalid Postal Code minLength: 1 description: Message explaining the address validation error type: readOnly: true allOf: - $ref: '#/components/schemas/address_validation_message_type' detail_code: nullable: true allOf: - $ref: '#/components/schemas/address_validation_detail_code' address_validation_code: title: address_validation_code type: string enum: - a1000 - a1001 - a1002 - a1003 - a1004 - a1005 - a1006 - a1007 - a1008 - r1000 - r1001 - r1002 - r1003 description: The error codes that can be returned by the address validation API address_validation_message_type: title: address_validation_message_type type: string enum: - error - warning - info description: >- The different types of messages that can be returned by the address validation API address_validation_detail_code: title: address_validation_detail_code type: string enum: - unsupported_country - non_supported_country - minimum_postal_code_verification_failed - street_does_not_match_unique_street_name - multiple_directionals - multiple_matches - suite_not_valid - suite_missing - incompatible_paired_labels - invalid_house_number - missing_house_number - invalid_box_number - invalid_charge_event - missing_box_number - missing_cmra_or_private_mail_box_number - suite_has_no_secondaries - postal_code_changed_or_added - state_province_changed_or_added - city_locality_changed_or_added - urbanization_changed - street_name_spelling_changed_or_added - street_name_type_changed_or_added - street_direction_changed_or_added - suite_type_changed_or_added - suite_unit_number_changed_or_added - double_dependent_locality_changed_or_added - subadministrative_area_changed_or_added - subnational_area_changed_or_added - po_box_changed_or_added - premise_type_changed_or_added - house_number_changed - organization_changed_or_added - partially_verified_to_state_level - partially_verified_to_city_level - partially_verified_to_street_level - partially_verified_to_premise_level - verified_to_state_level - verified_to_city_level - verified_to_street_level - verified_to_premise_level - verified_to_suite_level - coded_to_street_lavel - coded_to_neighborhood_level - coded_to_community_level - coded_to_state_level - coded_to_rooftop_level - coded_to_rooftop_interpolation_level - name_max_length_exceeded - phone_max_length_exceeded - company_name_max_length_exceeded - line1_min_max_length - line2_max_length_exceeded - line3_max_length_exceeded - city_locality_max_length_exceeded - state_province_max_length_exceeded - invalid_postal_code - country_invalid_length - address_not_found description: >- The detailed error codes that can be returned by the address validation API batch_status: title: batch_status type: string enum: - open - queued - processing - completed - completed_with_errors - archived - notifying - invalid description: The possible batch status values sort_dir: title: sort_dir type: string enum: - asc - desc description: | Controls the sort order of queries |Value |Description |:---------|:----------------------------------------------------- |`asc` |Return results in ascending order |`desc` |Return results in descending order batches_sort_by: title: batches_sort_by type: string enum: - ship_date - processed_at - created_at description: The possible batches sort by values list_batches_response_body: title: list_batches_response_body type: object description: A list batch response body required: - batches - total - page - pages - links additionalProperties: false properties: batches: type: array readOnly: true minItems: 0 items: allOf: - $ref: '#/components/schemas/batch' description: Batch description: Batch List total: type: integer format: int64 readOnly: true minimum: 0 example: 10 description: The total number of batches the API call returned page: type: integer format: int32 readOnly: true minimum: 1 example: 1 description: The page that is currently being read pages: type: integer format: int32 readOnly: true minimum: 1 example: 10 description: The total number of batch pages the API call returned links: readOnly: true allOf: - $ref: '#/components/schemas/pagination_link' batch: title: batch type: object description: > Batches are an advanced feature of ShipEngine designed for users who need to generate hundreds or thousands of labels at a time. required: - label_layout - label_format - batch_id - batch_number - external_batch_id - batch_notes - created_at - processed_at - errors - process_errors - warnings - completed - forms - count - batch_shipments_url - batch_labels_url - batch_errors_url - label_download - form_download - paperless_download - status additionalProperties: false properties: label_layout: readOnly: true default: 4x6 description: label layout allOf: - $ref: '#/components/schemas/label_layout' label_format: readOnly: true default: pdf allOf: - $ref: '#/components/schemas/label_format' batch_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the batch batch_number: readOnly: true type: string minLength: 0 description: The batch number. external_batch_id: type: string readOnly: true nullable: true minLength: 0 description: A string that uniquely identifies the external batch batch_notes: type: string readOnly: true nullable: true default: '' example: Batch for morning shipment description: Custom notes you can add for each created batch created_at: readOnly: true allOf: - $ref: '#/components/schemas/date_time' description: The date and time the batch was created in ShipEngine processed_at: nullable: true readOnly: true allOf: - $ref: '#/components/schemas/date_time' description: The date and time the batch was processed in ShipEngine errors: type: integer format: int32 readOnly: true minimum: 0 example: 2 description: The number of errors that occurred while generating the batch process_errors: errors: null type: array readOnly: true items: allOf: - $ref: '#/components/schemas/error' description: The errors associated with the failed API call warnings: type: integer format: int32 readOnly: true minimum: 0 example: 1 description: The number of warnings that occurred while generating the batch completed: type: integer format: int32 readOnly: true minimum: 0 example: 1 description: The number of labels generated in the batch forms: type: integer format: int32 readOnly: true minimum: 0 example: 3 description: The number of forms for customs that are available for download count: type: integer format: int32 readOnly: true minimum: 0 example: 2 description: 'The total of errors, warnings, and completed properties' batch_shipments_url: allOf: - $ref: '#/components/schemas/optional_link' description: The batch shipments endpoint batch_labels_url: allOf: - $ref: '#/components/schemas/optional_link' description: Link to batch labels query batch_errors_url: readOnly: true allOf: - $ref: '#/components/schemas/optional_link' description: Link to batch errors endpoint label_download: readOnly: true allOf: - $ref: '#/components/schemas/label_download' description: The label download for the batch form_download: readOnly: true allOf: - $ref: '#/components/schemas/optional_link' description: The form download for any customs that are needed paperless_download: readOnly: true allOf: - $ref: '#/components/schemas/paperless_download' description: >- The paperless details which may contain elements like `href`, `instructions` and `handoff_code`. status: readOnly: true allOf: - $ref: '#/components/schemas/batch_status' label_layout: title: label_layout type: string enum: - 4x6 - letter description: > The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. `4x6` is supported for all label formats, whereas `letter` (8.5" x 11") is only supported for `pdf` format. label_format: title: label_format type: string enum: - pdf - png - zpl description: > The possible file formats in which shipping labels can be downloaded. We recommend `pdf` format because it is supported by all carriers, whereas some carriers do not support the `png` or `zpl` formats. |Label Format | Supported Carriers |--------------|----------------------------------- |`pdf` | All carriers |`png` | `fedex`
`stamps_com`
`ups`
`usps` |`zpl` | `access_worldwide`
`apc`
`asendia`
`dhl_global_mail`
`dhl_express`
`dhl_express_australia`
`dhl_express_canada`
`dhl_express_worldwide`
`dhl_express_uk`
`dpd`
`endicia`
`fedex`
`fedex_uk`
`firstmile`
`imex`
`newgistics`
`ontrac`
`rr_donnelley`
`stamps_com`
`ups`
`usps` se_id: title: se_id type: string minLength: 1 maxLength: 25 pattern: '^se(-[a-z0-9]+)+$' example: se-28529731 description: >- A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc. label_download: title: label_download type: object description: > Reference to the various downloadable file formats for the generated label additionalProperties: false properties: href: allOf: - $ref: '#/components/schemas/url' description: 'The URL of the linked resource, if any' pdf: allOf: - $ref: '#/components/schemas/url' description: The URL for the pdf generated label png: allOf: - $ref: '#/components/schemas/url' description: The URL for the png generated label zpl: allOf: - $ref: '#/components/schemas/url' description: The URL for the zpl generated label paperless_download: title: paperless_download type: object description: > The paperless details which may contain elements like `href`, `instructions` and `handoff_code`. additionalProperties: false properties: href: allOf: - $ref: '#/components/schemas/url' description: 'The URL of the linked resource, if any' instructions: type: string nullable: true default: null description: | The instructions for the paperless download. handoff_code: type: string nullable: true default: null description: | The handoff code for the paperless download. create_batch_request: title: create_batch_request oneOf: - $ref: '#/components/schemas/create_batch_request_body' - $ref: '#/components/schemas/create_and_process_batch_request_body' create_batch_request_body: title: create_batch_request_body type: object description: A create batch request body additionalProperties: false properties: external_batch_id: allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the external batch batch_notes: type: string minLength: 1 example: This is my batch description: Add custom messages for a particular batch shipment_ids: type: array items: allOf: - $ref: '#/components/schemas/se_id' description: Array of shipment IDs used in the batch rate_ids: type: array items: type: string minLength: 1 allOf: - $ref: '#/components/schemas/se_id' description: Array of rate IDs used in the batch create_and_process_batch_request_body: title: create_and_process_batch_request_body type: object description: A create and process batch request body additionalProperties: false properties: external_batch_id: allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the external batch batch_notes: type: string minLength: 1 example: This is my batch description: Add custom messages for a particular batch shipment_ids: type: array items: allOf: - $ref: '#/components/schemas/se_id' description: Array of shipment IDs used in the batch rate_ids: type: array items: type: string minLength: 1 allOf: - $ref: '#/components/schemas/se_id' description: Array of rate IDs used in the batch process_labels: type: object description: The information used to process the batch properties: create_batch_and_process_labels: type: boolean description: 'When ''true'', the batch will be enqueued for processing' ship_date: allOf: - $ref: '#/components/schemas/date_time' description: The Ship date the batch is being processed for label_layout: type: string default: 4x6 allOf: - $ref: '#/components/schemas/label_layout' label_format: default: pdf allOf: - $ref: '#/components/schemas/label_format' display_scheme: default: label allOf: - $ref: '#/components/schemas/display_scheme' description: The display format that the label should be shown in. display_scheme: title: display_scheme type: string enum: - label - qr_code - label_and_qr_code - paperless - label_and_paperless description: The display format that the label should be shown in. create_batch_response_body: title: create_batch_response_body type: object description: A create batch response body additionalProperties: false allOf: - $ref: '#/components/schemas/batch' get_batch_by_external_id_response_body: title: get_batch_by_external_id_response_body type: object description: A get batch by external id response body additionalProperties: false allOf: - $ref: '#/components/schemas/batch' get_batch_by_id_response_body: title: get_batch_by_id_response_body type: object description: A get batch by id response body additionalProperties: false allOf: - $ref: '#/components/schemas/batch' add_to_batch_request_body: title: add_to_batch_request_body type: object description: An add to batch request body additionalProperties: false allOf: - $ref: '#/components/schemas/modify_batch' modify_batch: title: modify_batch type: object description: A modify batch object additionalProperties: false properties: shipment_ids: type: array items: allOf: - $ref: '#/components/schemas/se_id' description: The Shipment ID to be modified on the batch description: The Shipment Ids to be modified on the batch rate_ids: type: array items: allOf: - $ref: '#/components/schemas/se_id' description: The Rate ID to be modified on the batch description: Array of Rate IDs to be modifed on the batch list_batch_errors_response_body: title: list_batch_errors_response_body type: object description: A batch errors response body required: - errors - links additionalProperties: false properties: errors: type: array readOnly: true default: [] items: $ref: '#/components/schemas/batch_response_error' description: The errors currently associated with the batch links: readOnly: true allOf: - $ref: '#/components/schemas/pagination_link' batch_response_error: title: batch_response_error type: object description: A batch response error additionalProperties: false properties: error: type: string readOnly: true minLength: 1 example: Recipient address has not been verified. description: Error message associated with the shipment. shipment_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the shipment external_shipment_id: readOnly: true type: string description: An external shipment id associated with the shipment process_batch_request_body: title: process_batch_request_body type: object description: A process batch request body additionalProperties: false properties: ship_date: allOf: - $ref: '#/components/schemas/date_time' description: The Ship date the batch is being processed for label_layout: type: string default: 4x6 allOf: - $ref: '#/components/schemas/label_layout' label_format: default: pdf allOf: - $ref: '#/components/schemas/label_format' display_scheme: default: label allOf: - $ref: '#/components/schemas/display_scheme' description: The display format that the label should be shown in. remove_from_batch_request_body: title: remove_from_batch_request_body type: object description: A modify batch request body additionalProperties: false allOf: - $ref: '#/components/schemas/modify_batch' get_carriers_response_body: title: get_carriers_response_body allOf: - $ref: '#/components/schemas/list_carriers_response_body' - $ref: '#/components/schemas/error_response_body' list_carriers_response_body: title: list_carriers_response_body type: object description: A carrier list response body additionalProperties: false required: - carriers properties: carriers: type: array readOnly: true items: readOnly: true allOf: - $ref: '#/components/schemas/carrier' description: The carrier response body carrier: title: carrier type: object description: | A carrier object that represents a provider such as UPS, USPS, DHL, etc that has been tied to the current account. additionalProperties: false properties: carrier_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the carrier. carrier_code: readOnly: true allOf: - $ref: '#/components/schemas/carrier_code' description: > The [shipping carrier](https://www.shipengine.com/docs/carriers/setup/) who will ship the package, such as `fedex`, `dhl_express`, `stamps_com`, etc. account_number: type: string readOnly: true minLength: 1 example: account_570827 description: The account number that the carrier is connected to. requires_funded_amount: type: boolean readOnly: true description: Indicates whether the carrier requires funding to use its services balance: type: number format: double readOnly: true example: 3799.52 minimum: 0 description: Current available balance nickname: type: string readOnly: true minLength: 1 example: ShipEngine Account - Stamps.com description: Nickname given to the account when initially setting up the carrier. friendly_name: type: string readOnly: true minLength: 1 example: Stamps.com description: Screen readable name primary: type: boolean readOnly: true description: >- Is this the primary carrier that is used by default when no carrier is specified in label/shipment creation has_multi_package_supporting_services: type: boolean readOnly: true description: Carrier supports multiple packages per shipment supports_label_messages: type: boolean readOnly: true description: The carrier supports adding custom label messages to an order. disabled_by_billing_plan: type: boolean readOnly: true description: >- The carrier is disabled by the current ShipEngine account's billing plan. services: type: array readOnly: true items: readOnly: true allOf: - $ref: '#/components/schemas/service' description: A list of services that are offered by the carrier packages: type: array readOnly: true items: readOnly: true allOf: - $ref: '#/components/schemas/package_type' description: A list of package types that are supported by the carrier options: type: array readOnly: true items: readOnly: true allOf: - $ref: '#/components/schemas/carrier_advanced_option' description: A list of options that are available to that carrier carrier_code: title: carrier_code type: string pattern: '^[a-z0-9]+(_[a-z0-9]+)*$' example: dhl_express description: > A [shipping carrier](https://www.shipengine.com/docs/carriers/setup/), such as `fedex`, `dhl_express`, `stamps_com`, etc. service: title: service type: object description: A service offered by the carrier additionalProperties: false properties: carrier_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the carrier carrier_code: allOf: - $ref: '#/components/schemas/se_id' service_code: type: string minLength: 1 readOnly: true example: usps_media_mail description: service code name: type: string minLength: 1 readOnly: true example: USPS First Class Mail description: User friendly service name domestic: type: boolean readOnly: true description: Supports domestic shipping international: type: boolean readOnly: true description: Supports international shipping. is_multi_package_supported: type: boolean readOnly: true description: Carrier supports multiple packages per shipment package_type: title: package_type type: object description: A package type that a carrier supports for shipment. required: - name - package_code additionalProperties: false properties: package_id: allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the package. package_code: allOf: - $ref: '#/components/schemas/package_code' name: type: string minLength: 1 maxLength: 50 example: laptop_box dimensions: allOf: - $ref: '#/components/schemas/dimensions' description: The custom dimensions for the package. description: type: string maxLength: 500 example: Packaging for laptops nullable: true description: Provides a helpful description for the custom package. package_code: title: package_code type: string minLength: 1 maxLength: 50 pattern: '^[a-z0-9]+(_[a-z0-9]+)*$' example: small_flat_rate_box description: > A [package type](https://www.shipengine.com/docs/reference/list-carrier-packages/), such as `thick_envelope`, `small_flat_rate_box`, `large_package`, etc. Use the code `package` for custom or unknown package types. dimensions: title: dimensions type: object description: The dimensions of a package required: - unit - length - width - height additionalProperties: false properties: unit: default: inch allOf: - $ref: '#/components/schemas/dimension_unit' length: type: number format: double minimum: 0 default: 0 description: 'The length of the package, in the specified unit' width: type: number format: double minimum: 0 default: 0 description: 'The width of the package, in the specified unit' height: type: number format: double minimum: 0 default: 0 description: 'The length of the package, in the specified unit' dimension_unit: title: dimension_unit type: string enum: - inch - centimeter description: The dimension units that are supported by ShipEngine. carrier_advanced_option: title: carrier_advanced_option type: object description: Advanced options that are specific to the carrier additionalProperties: false properties: name: type: string minLength: 1 readOnly: true example: contains_alcohol description: Name of advanced option default_value: type: string minLength: 1 readOnly: true example: false description: Default value of option description: type: string minLength: 0 readOnly: true description: Description of option get_carrier_by_id_response_body: title: get_carrier_by_id_response_body type: object description: A get carrier by id response body additionalProperties: false allOf: - $ref: '#/components/schemas/carrier' add_funds_to_carrier_request_body: title: add_funds_to_carrier_request_body type: object description: An add funds to carrier request body additionalProperties: false allOf: - $ref: '#/components/schemas/monetary_value' monetary_value: title: monetary_value type: object description: > A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance. required: - currency - amount additionalProperties: false properties: currency: allOf: - $ref: '#/components/schemas/currency' amount: type: number format: double minimum: 0 description: 'The monetary amount, in the specified currency.' currency: title: currency type: string description: > The currencies that are supported by ShipEngine are the ones that specified by ISO 4217: https://www.iso.org/iso-4217-currency-codes.html add_funds_to_carrier_response_body: title: add_funds_to_carrier_response_body type: object description: The current balance of the requested carrier account required: - balance additionalProperties: false properties: balance: readOnly: true allOf: - $ref: '#/components/schemas/monetary_value' description: The current balance of the account get_carrier_options_response_body: title: get_carrier_options_response_body type: object description: A carrier list options response body additionalProperties: false properties: options: type: array readOnly: true items: readOnly: true allOf: - $ref: '#/components/schemas/carrier_advanced_option' description: Carrer options description: AN array of carrier options list_carrier_package_types_response_body: title: list_carrier_package_types_response_body type: object description: A list carrier package types response body additionalProperties: false properties: packages: type: array readOnly: true items: readOnly: true allOf: - $ref: '#/components/schemas/package_type' description: Custom Package Type items description: An array of custom package types list_carrier_services_response_body: title: list_carrier_services_response_body type: object description: A carrier list services response body additionalProperties: false properties: services: type: array readOnly: true items: readOnly: true allOf: - $ref: '#/components/schemas/service' description: A carrier service description: An array of services associated with the carrier carrier_name: title: carrier_name type: string enum: - access_worldwide - amazon_buy_shipping - amazon_shipping_uk - apc - asendia - australia_post - canada_post - dhl_ecommerce - dhl_express - dhl_express_au - dhl_express_ca - dhl_express_uk - dpd - endicia - fedex - fedex_uk - firstmile - imex - newgistics - ontrac - purolator_canada - royal_mail - rr_donnelley - seko - sendle - stamps_com - ups description: The shipping carriers that are supported by ShipEngine connect_carrier_request_body: title: connect_carrier_request_body oneOf: - $ref: '#/components/schemas/connect_access_worldwide_request_body' - $ref: '#/components/schemas/connect_amazon_buy_shipping_request_body' - $ref: '#/components/schemas/connect_amazon_shipping_uk' - $ref: '#/components/schemas/connect_apc_request_body' - $ref: '#/components/schemas/connect_asendia_request_body' - $ref: '#/components/schemas/connect_australia_post_request_body' - $ref: '#/components/schemas/connect_canada_post_request_body' - $ref: '#/components/schemas/connect_dhl_ecommerce_request_body' - $ref: '#/components/schemas/connect_dhl_express_request_body' - $ref: '#/components/schemas/connect_dhl_express_au_request_body' - $ref: '#/components/schemas/connect_dhl_express_ca_request_body' - $ref: '#/components/schemas/connect_dhl_express_uk_request_body' - $ref: '#/components/schemas/connect_dpd_request_body' - $ref: '#/components/schemas/connect_endicia_request_body' - $ref: '#/components/schemas/connect_fedex_request_body' - $ref: '#/components/schemas/connect_fedex_uk_request_body' - $ref: '#/components/schemas/connect_firstmile_request_body' - $ref: '#/components/schemas/connect_imex_request_body' - $ref: '#/components/schemas/connect_newgistics_request_body' - $ref: '#/components/schemas/connect_ontrac_request_body' - $ref: '#/components/schemas/connect_purolator_request_body' - $ref: '#/components/schemas/connect_royal_mail_request_body' - $ref: '#/components/schemas/connect_rr_donnelley_request_body' - $ref: '#/components/schemas/connect_seko_request_body' - $ref: '#/components/schemas/connect_sendle_request_body' - $ref: '#/components/schemas/connect_stamps_request_body' - $ref: '#/components/schemas/connect_ups_request_body' connect_access_worldwide_request_body: title: connect_access_worldwide_request_body type: object description: An Access Worldwide account information request body required: - nickname - username - password additionalProperties: false properties: nickname: type: string minLength: 1 example: Stamps.com description: The nickname associated with the carrier connection username: type: string minLength: 1 description: Access Worldwide Username password: type: string minLength: 1 description: Access Worldwide Password connect_amazon_buy_shipping_request_body: title: connect_amazon_buy_shipping_request_body type: object description: An Amazon account information request body required: - nickname - merchant_seller_id - email - mws_auth_token additionalProperties: false properties: nickname: type: string minLength: 1 example: Test Amazon Buy Shipping description: Nickname to be associated with the account connection merchant_seller_id: type: string minLength: 1 mws_auth_token: type: string minLength: 1 email: allOf: - $ref: '#/components/schemas/email' email: title: email type: string format: email minLength: 1 example: john.doe@example.com description: An email address. connect_amazon_shipping_uk: title: connect_amazon_shipping_uk type: object description: An Amazon Shipping UK account information request body required: - nickname - auth_code additionalProperties: false properties: nickname: type: string minLength: 1 example: Stamps.com description: The nickname associated with the carrier connection auth_code: type: string minLength: 1 description: Amazon UK Shipping auth code. connect_apc_request_body: title: connect_apc_request_body type: object description: An APC account information request body required: - nickname - username - password additionalProperties: false properties: nickname: type: string minLength: 1 example: APC carrier account description: The nickname for the APC account username: type: string minLength: 1 example: john_doe description: The username for the APC account password: type: string minLength: 1 example: 12345 description: The password for the APC account connect_asendia_request_body: title: connect_asendia_request_body type: object description: An Asendia account information request body required: - nickname - account_number - ftp_username - ftp_password additionalProperties: false properties: nickname: type: string minLength: 1 example: Asendia account description: The nickname of the Asendia account account_number: type: string minLength: 1 description: Asendia account number ftp_username: type: string minLength: 1 description: FTP username ftp_password: type: string minLength: 1 description: FTP password connect_australia_post_request_body: title: connect_australia_post_request_body type: object description: An Australia Post account information request body required: - account_number - api_key - api_secret - nickname additionalProperties: false properties: account_number: type: string minLength: 1 description: Account number api_key: type: string minLength: 1 description: API key api_secret: type: string minLength: 1 description: API secret nickname: type: string minLength: 1 description: Nickname connect_canada_post_request_body: title: connect_canada_post_request_body type: object description: A Canada Post account information request body required: - nickname - api_key - api_secret - account_number - contract_id additionalProperties: false properties: nickname: type: string minLength: 1 description: Nickname api_key: type: string minLength: 1 description: Canada Post Account API Key api_secret: type: string minLength: 1 description: Canada Post Account API Secret account_number: type: string minLength: 1 description: Canada Post Account Number contract_id: type: string minLength: 1 description: Canada Post Account Contract ID connect_dhl_ecommerce_request_body: title: connect_dhl_ecommerce_request_body type: object description: A DHL Ecommerce account information request body required: - nickname - client_id - username - password - pickup_number - distribution_center additionalProperties: false properties: nickname: type: string minLength: 1 description: A nickname to help you identify this account client_id: type: string minLength: 1 description: The client id username: type: string minLength: 1 description: The account username password: type: string minLength: 1 description: The account password pickup_number: type: string minLength: 1 description: The pickup number distribution_center: type: string minLength: 1 description: The distribution center api_key: type: string minLength: 1 description: > The DHL E-Commerce API key. This field is optional, but if not set you will not be able to get rates for this account. api_secret: type: string minLength: 1 description: > The DHL E-Commerce API secret. This field is optional, but if not set you will not be able to get rates for this account. ancillary_endorsement: allOf: - $ref: '#/components/schemas/ancillary_service_endorsement' account_number: type: string minLength: 1 deprecated: true description: Account number ftp_username: type: string minLength: 1 deprecated: true description: FTP username ftp_password: type: string minLength: 1 deprecated: true description: FTP password sold_to: type: string description: Sold To field registration_id: type: string software_name: type: string ancillary_service_endorsement: title: ancillary_service_endorsement type: string enum: - none - return_service_requested - forwarding_service_requested - address_service_requested - change_service_requested - leave_if_no_response description: > [Ancillary service endorsements](https://pe.usps.com/text/qsg300/Q507.htm) are used by mailers to request an addressee's new address and to provide the carrier with instructions on how to handle packages that are undeliverable as addressed. | Ancillary Service Endorsement | Description |--------------------------------|----------------------------------------------------- | `none` | No ancillary service is requested. Depending on the carrier servive, the package may be forwarded, returned, or discarded. | `return_service_requested` | The package is returned to the sender. If possible, notification of the new address is is included with the returned package. | `forwarding_service_requested` | Forward the package to the new address, if possible; otherwise, return it to the sender. | `address_service_requested` | Forward the package to the new address, if possible; otherwise, return it to the sender. This is similar to `forwarding_service_requested`, but different restrictions and charges may apply. | `change_service_requested` | The package is discarded. If possible, notification of the new address is sent to the sender. | `leave_if_no_response` | connect_dhl_express_request_body: title: connect_dhl_express_request_body type: object description: A DHL express account information request body required: - nickname - account_number additionalProperties: false properties: nickname: type: string minLength: 1 description: Nickname account_number: type: string minLength: 1 description: Account number site_id: type: string minLength: 1 description: Required if password is provided password: type: string minLength: 1 description: Required if site id is provided country_code: allOf: - $ref: '#/components/schemas/country_code' connect_dhl_express_au_request_body: title: connect_dhl_express_au_request_body type: object description: A DHL Express AU account information request body required: - nickname - account_number additionalProperties: false properties: nickname: type: string minLength: 1 description: Nickname account_number: type: string minLength: 1 description: Account number connect_dhl_express_ca_request_body: title: connect_dhl_express_ca_request_body type: object description: A DHL Express CA account information request body required: - nickname - account_number additionalProperties: false properties: nickname: type: string minLength: 1 description: Nickname account_number: type: string minLength: 1 description: Account number connect_dhl_express_uk_request_body: title: connect_dhl_express_uk_request_body type: object description: A DHL Express UK account information request body required: - account_number - site_id - password - nickname additionalProperties: false properties: account_number: type: string minLength: 1 description: Account number site_id: allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the site password: type: string minLength: 1 description: Password nickname: type: string minLength: 1 description: Nickname connect_dpd_request_body: title: connect_dpd_request_body type: object description: A DPD account information request body required: - account_number - password - nickname additionalProperties: false properties: account_number: type: string minLength: 1 description: Account number password: type: string minLength: 1 description: Password nickname: type: string minLength: 1 description: Nickname connect_endicia_request_body: title: connect_endicia_request_body type: object description: An Endicia account information request body required: - nickname - account - passphrase additionalProperties: false properties: nickname: type: string minLength: 1 description: Nickname account: type: string minLength: 1 description: Account passphrase: type: string minLength: 1 description: Passphrase connect_fedex_request_body: title: connect_fedex_request_body type: object description: A Fedex account information request body required: - account_number - address1 - city - country_code - email - first_name - last_name - phone - postal_code - state - nickname - agree_to_eula additionalProperties: false properties: account_number: type: string minLength: 1 description: Account number address1: type: string minLength: 1 description: Address address2: type: string minLength: 1 description: Address city: type: string minLength: 1 description: The city company: type: string minLength: 1 description: The company country_code: type: string minLength: 1 description: Country code email: allOf: - $ref: '#/components/schemas/email' description: The email address first_name: type: string minLength: 1 description: First name last_name: type: string minLength: 1 description: Last name phone: type: string minLength: 1 description: Phone number postal_code: type: string minLength: 1 description: Postal Code state: type: string minLength: 1 description: State nickname: type: string minLength: 1 description: Nickname agree_to_eula: type: boolean description: Boolean signaling agreement to the Fedex End User License Agreement meter_number: type: string minLength: 1 description: Meter number connect_fedex_uk_request_body: title: connect_fedex_uk_request_body type: object description: A Fedex UK account information request body required: - account_number - address1 - city - country_code - email - first_name - last_name - phone - postal_code - state - nickname - agree_to_eula additionalProperties: false properties: account_number: type: string minLength: 1 description: Account number address1: type: string minLength: 1 description: Address address2: type: string minLength: 1 description: Address city: type: string minLength: 1 description: The city company: type: string minLength: 1 description: The company country_code: type: string minLength: 1 description: Country code email: allOf: - $ref: '#/components/schemas/email' description: The email address first_name: type: string minLength: 1 description: First name last_name: type: string minLength: 1 description: Last name phone: type: string minLength: 1 description: Phone number postal_code: type: string minLength: 1 description: Postal Code state: type: string minLength: 1 description: State nickname: type: string minLength: 1 description: Nickname agree_to_eula: type: boolean description: Boolean signaling agreement to the Fedex End User License Agreement meter_number: type: string minLength: 1 description: Meter number connect_firstmile_request_body: title: connect_firstmile_request_body type: object description: A First Mile account information request body required: - nickname - mailer_id - password additionalProperties: false properties: nickname: type: string minLength: 1 description: Nickname mailer_id: allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the mailer profile_name: type: string minLength: 1 description: Profile name password: type: string minLength: 1 description: Password connect_imex_request_body: title: connect_imex_request_body type: object description: An Imex account information request body required: - nickname - username - password additionalProperties: false properties: nickname: type: string minLength: 1 description: Nickname username: type: string minLength: 1 description: Username password: type: string minLength: 1 description: Password connect_newgistics_request_body: title: connect_newgistics_request_body type: object description: A Newgistics account information request body required: - induction_site - nickname additionalProperties: false properties: merchant_id: type: integer format: int32 minimum: 0 description: Merchant id mailer_id: type: integer format: int32 minimum: 0 description: Mailer id induction_site: type: string minLength: 1 description: Induction site nickname: type: string minLength: 1 description: Nickname connect_ontrac_request_body: title: connect_ontrac_request_body type: object description: An Ontrac account information request body required: - nickname - account_number - password additionalProperties: false properties: nickname: type: string minLength: 1 description: Nickname account_number: type: string minLength: 1 description: Account number password: type: string minLength: 1 description: Password connect_purolator_request_body: title: connect_purolator_request_body type: object description: A Purolator account information request body required: - account_number - activation_key - nickname additionalProperties: false properties: account_number: type: string minLength: 1 description: Account number activation_key: type: string minLength: 1 description: Activation key nickname: type: string minLength: 1 description: Nickname connect_royal_mail_request_body: title: connect_royal_mail_request_body type: object description: A Royal Mail account information request body required: - account_number - contact_name - city - postal_code - nickname additionalProperties: false properties: account_number: type: string minLength: 1 description: Account number oba_email: allOf: - $ref: '#/components/schemas/email' description: The oba email address contact_name: type: string minLength: 1 description: Contact name email: allOf: - $ref: '#/components/schemas/email' description: The email address company_name: type: string minLength: 1 description: Company name street_line1: type: string minLength: 1 description: Street line1 street_line2: type: string minLength: 1 description: Street line2 street_line3: type: string minLength: 1 description: Street line3 city: type: string minLength: 1 description: City postal_code: type: string minLength: 1 description: Postal code phone: type: string minLength: 1 description: Phone nickname: type: string minLength: 1 description: Nickname connect_rr_donnelley_request_body: title: connect_rr_donnelley_request_body type: object description: A RR Donnelley account information request body required: - nickname - username - password additionalProperties: false properties: nickname: type: string minLength: 1 description: Nickname username: type: string minLength: 1 description: Username password: type: string minLength: 1 description: Password connect_seko_request_body: title: connect_seko_request_body type: object description: A SEKO account information request body required: - nickname - access_key additionalProperties: false properties: nickname: type: string minLength: 1 description: Nickname access_key: type: string minLength: 1 description: Seko Account Access Key connect_sendle_request_body: title: connect_sendle_request_body type: object description: A Sendle account information request body required: - nickname - sendle_id - api_key additionalProperties: false properties: nickname: type: string minLength: 1 description: Nickname sendle_id: allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the sendle api_key: type: string minLength: 1 description: API key connect_stamps_request_body: title: connect_stamps_request_body type: object description: A Stamps account information request body required: - nickname - username - password additionalProperties: false properties: nickname: type: string minLength: 1 description: Nickname username: type: string minLength: 1 description: Username password: type: string minLength: 1 description: Password connect_ups_request_body: title: connect_ups_request_body type: object description: A UPS account information request body required: - nickname - account_number - account_country_code - account_postal_code - first_name - last_name - company - address1 - city - state - postal_code - country_code - email - phone - agree_to_technology_agreement additionalProperties: false properties: nickname: type: string minLength: 1 description: Nickname account_number: type: string minLength: 1 description: Account number account_country_code: type: string minLength: 1 description: Account country code account_postal_code: type: string minLength: 1 description: Account postal code title: type: string minLength: 1 description: Title first_name: type: string minLength: 1 description: First name last_name: type: string minLength: 1 description: Last name company: type: string minLength: 1 description: Company address1: type: string minLength: 1 description: Address Line 1 address2: type: string minLength: 1 description: Address Line 2 city: type: string minLength: 1 description: City state: type: string minLength: 1 description: State postal_code: type: string minLength: 1 description: Postal code country_code: type: string minLength: 1 description: Country code email: allOf: - $ref: '#/components/schemas/email' description: The email address phone: type: string minLength: 1 description: Phone invoice: allOf: - $ref: '#/components/schemas/ups_invoice' description: The UPS invoice invoice_amount: format: double type: number description: The invoice amount invoice_currency_code: type: string description: The invoice currency code agree_to_technology_agreement: type: boolean description: >- The Agreement to the [UPS Technology Agreement](https://www.ups.com/assets/resources/media/UTA_with_EUR.pdf) ups_invoice: title: ups_invoice type: object description: UPS invoice additionalProperties: false properties: invoice_date: type: string format: date-time minLength: 1 description: invoice date invoice_number: type: string minLength: 1 description: invoice number control_id: allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the control invoice_amount: type: number format: double minimum: 0 invoice_currency_code: type: string connect_carrier_response_body: title: connect_carrier_response_body type: object description: A connect account response body required: - carrier_id additionalProperties: false properties: carrier_id: allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the carrier carrier_name_with_settings: title: carrier_name_with_settings type: string enum: - dhl_express - fedex - newgistics - ups description: The shipping carriers for which ShipEngine supports carrier settings get_carrier_settings_response_body: title: get_carrier_settings_response_body oneOf: - $ref: '#/components/schemas/dhl_express_settings_response_body' - $ref: '#/components/schemas/fedex_settings_response_body' - $ref: '#/components/schemas/ups_settings_response_body' dhl_express_settings_response_body: title: dhl_express_settings_response_body type: object description: A DHL Express response body additionalProperties: false allOf: - $ref: '#/components/schemas/dhl_express_account_settings' dhl_express_account_settings: title: dhl_express_account_settings type: object description: A DHL Express account settings additionalProperties: false properties: nickname: type: string minLength: 1 description: Account nickname should_hide_account_number_on_archive_doc: type: boolean description: >- Indicates if the account number should be hidden on the archive documentation is_primary_account: type: boolean description: Indicates if this is primary account fedex_settings_response_body: title: fedex_settings_response_body type: object description: A Fedex settings response body additionalProperties: false allOf: - $ref: '#/components/schemas/fedex_account_settings_request_body' fedex_account_settings_request_body: title: fedex_account_settings_request_body type: object description: A Fedex account settings request body additionalProperties: false allOf: - $ref: '#/components/schemas/fedex_account_settings' fedex_account_settings: title: fedex_account_settings type: object description: A Fedex account settings request body additionalProperties: false properties: nickname: type: string minLength: 1 description: Account nickname pickup_type: allOf: - $ref: '#/components/schemas/fedex_pickup_type' smart_post_hub: allOf: - $ref: '#/components/schemas/smart_post_hub' smart_post_endorsement: allOf: - $ref: '#/components/schemas/ancillary_service_endorsement' is_primary_account: type: boolean signature_image: type: string letterhead_image: type: string fedex_pickup_type: title: fedex_pickup_type type: string enum: - none - regular_pickup - request_courier - drop_box - business_service_center - station description: > Tax identifier type for customs declaration |Pickup Type |Description |--------------------------|----------------------------------------- |`none` | Not specified |`regular_pickup` | You already have a daily pickup scheduled with FedEx |`request_courier` | You will call FedEx to request a courier |`drop_box` | You will drop-off packages in a FedEx drop box |`business_service_center` | You will drop-off packages at an authorized FedEx business service center |`station` | You will drop-off the package at a FedEx Station smart_post_hub: title: smart_post_hub type: string enum: - none - allentown_pa - atlanta_ga - baltimore_md - charlotte_nc - chino_ca - dallas_tx - denver_co - detroit_mi - edison_nj - grove_city_oh - groveport_oh - houston_tx - indianapolis_in - kansas_city_ks - los_angeles_ca - martinsburg_wv - memphis_tn - minneapolis_mn - new_berlin_wi - northborough_ma - orlando_fl - phoneix_az - pittsburgh_pa - reno_nv - sacramento_ca - salt_lake_city_ut - seattle_wa - st_louis_mo - windsor_ct - newark_ny - south_brunswick_nj - scranton_pa - wheeling_il description: The possible smart post hub values ups_settings_response_body: title: ups_settings_response_body type: object description: A UPS settings response body additionalProperties: false allOf: - $ref: '#/components/schemas/ups_account_settings' ups_account_settings: title: ups_account_settings type: object description: UPS account settings additionalProperties: false properties: nickname: type: string minLength: 1 description: nickname is_primary_account: type: boolean description: Indicates if this is the primary UPS account pickup_type: allOf: - $ref: '#/components/schemas/ups_pickup_type' use_carbon_neutral_shipping_program: type: boolean description: The use carbon neutral shipping program use_ground_freight_pricing: type: boolean description: The use ground freight pricing use_consolidation_services: type: boolean description: The use consolidation services use_order_number_on_mail_innovations_labels: type: boolean description: The use order number on mail innovations labels mail_innovations_endorsement: allOf: - $ref: '#/components/schemas/ancillary_service_endorsement' mail_innovations_cost_center: type: string minLength: 0 description: mail innovations cost center use_negotiated_rates: type: boolean description: The use negotiated rates account_postal_code: type: string minLength: 5 description: account postal code invoice: allOf: - $ref: '#/components/schemas/ups_invoice' description: The invoice ups_pickup_type: title: ups_pickup_type type: string enum: - daily_pickup - occasional_pickup - customer_counter description: The possible ups pickup type values update_carrier_settings_request_body: title: update_carrier_settings_request_body oneOf: - $ref: '#/components/schemas/update_dhl_express_settings_request_body' - $ref: '#/components/schemas/update_fedex_settings_request_body' - $ref: '#/components/schemas/update_newgistics_settings_request_body' - $ref: '#/components/schemas/update_ups_settings_request_body' - $ref: '#/components/schemas/update_amazon_buy_shipping_request_body' update_dhl_express_settings_request_body: title: update_dhl_express_settings_request_body type: object description: An update dhl express settings request body additionalProperties: false allOf: - $ref: '#/components/schemas/dhl_express_account_settings' update_fedex_settings_request_body: title: update_fedex_settings_request_body type: object description: An update Fedex settings request body additionalProperties: false allOf: - $ref: '#/components/schemas/fedex_account_settings' update_newgistics_settings_request_body: title: update_newgistics_settings_request_body type: object description: A newgistics account settings request body additionalProperties: false properties: include_barcode_with_order_number: type: boolean receive_email_on_manifest_processing: type: boolean update_ups_settings_request_body: title: update_ups_settings_request_body type: object description: An update UPS settings request body additionalProperties: false allOf: - $ref: '#/components/schemas/ups_account_settings' update_amazon_buy_shipping_request_body: title: update_amazon_buy_shipping_request_body type: object description: An amazon buy shipping account settings request body additionalProperties: false properties: email: type: string minLength: 1 description: Email disconnect_insurer_response_body: title: disconnect_insurer_response_body type: object connect_insurer_request_body: title: connect_insurer_request_body type: object description: A create shipsurance connection request body required: - email - policy_id additionalProperties: false properties: email: allOf: - $ref: '#/components/schemas/email' policy_id: type: string minLength: 1 connect_insurer_response_body: title: connect_insurer_response_body type: object download_file_pdf_response_body: title: download_file_pdf_response_body type: string format: binary download_file_png_response_body: title: download_file_png_response_body type: string format: binary download_file_zpl_response_body: title: download_file_zpl_response_body type: string format: binary list_webhooks_response_body: title: list_webhooks_response_body type: array description: A webhook list response body items: allOf: - $ref: '#/components/schemas/webhook' description: The webhook list response body webhook: title: webhook type: object description: A webhook additionalProperties: false properties: webhook_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the webhook url: allOf: - $ref: '#/components/schemas/url' example: 'https://[YOUR ENDPOINT ID].x.requestbin.com' description: The url that the webhook sends the request to event: allOf: - $ref: '#/components/schemas/webhook_event' headers: type: array items: allOf: - $ref: '#/components/schemas/webhook_header' description: Array of custom webhook headers webhook_event: title: webhook_event type: string enum: - batch - carrier_connected - order_source_refresh_complete - rate - report_complete - sales_orders_imported - track description: The possible webook event values webhook_header: title: webhook_header type: object description: Optional header to be specified in webhook properties: key: $ref: '#/components/schemas/key' value: $ref: '#/components/schemas/value' required: - key - value key: title: key type: string min_length: 1 description: Key/name of a header example: custom-key value: title: value type: string description: Value of a header example: custom-value create_webhook_request_body: title: create_webhook_request_body type: object description: A create webhook request body required: - event - url additionalProperties: false properties: event: allOf: - $ref: '#/components/schemas/webhook_event' url: allOf: - $ref: '#/components/schemas/url' example: 'https://[YOUR ENDPOINT ID].x.requestbin.com' description: The url that the webhook sends the request to headers: type: array items: allOf: - $ref: '#/components/schemas/webhook_header' description: Array of custom webhook headers create_webhook_response_body: title: create_webhook_response_body type: object description: A webhook response body additionalProperties: false required: - webhook_id - url - event allOf: - $ref: '#/components/schemas/webhook' get_webhook_by_id_response_body: title: get_webhook_by_id_response_body type: object description: A get webhook id response body additionalProperties: false required: - webhook_id - url - event allOf: - $ref: '#/components/schemas/webhook' update_webhook_request_body: title: update_webhook_request_body type: object description: An update webhook request body additionalProperties: false properties: url: allOf: - $ref: '#/components/schemas/url' example: 'https://[YOUR ENDPOINT ID].x.requestbin.com' description: The url that the wehbook sends the request headers: type: array items: allOf: - $ref: '#/components/schemas/webhook_header' description: Array of custom webhook headers add_funds_to_insurance_request_body: title: add_funds_to_insurance_request_body type: object description: An add funds to insurance request body additionalProperties: false allOf: - $ref: '#/components/schemas/monetary_value' add_funds_to_insurance_response_body: title: add_funds_to_insurance_response_body type: object description: Add funds to insurance response body additionalProperties: false allOf: - $ref: '#/components/schemas/monetary_value' get_insurance_balance_response_body: title: get_insurance_balance_response_body type: object description: A get insurance balance response body additionalProperties: false allOf: - $ref: '#/components/schemas/monetary_value' label_status: title: label_status type: string enum: - processing - completed - error - voided description: > The possible statuses that a [shipping label](https://www.shipengine.com/docs/labels/create-a-label/) can be in. |Status |Description |:------------|:----------------------------------------------------- |`processing` |When labels are created in a [batch](https://www.shipengine.com/docs/labels/bulk/), it may take a few minutes for all of the labels in the batch to be created. During this period, they will be in `processing` status. |`completed` |The label was successfully created |`error` |The label could not be created due to an error, such as an invalid delivery address |`voided` |The label has been [voided](https://www.shipengine.com/docs/labels/voiding/) service_code: title: service_code type: string pattern: '^[a-z0-9]+(_[a-z0-9-]+)* ?$' example: usps_first_class_mail description: > A [carrier service](https://www.shipengine.com/docs/shipping/use-a-carrier-service/), such as `fedex_ground`, `usps_first_class_mail`, `flat_rate_envelope`, etc. list_labels_response_body: title: list_labels_response_body type: object description: A list label response body required: - labels additionalProperties: false properties: labels: type: array minItems: 0 description: > The labels that matched the query criteria. If no matching labels were found, then this array is empty; otherwise, it contains one page of results. The last page of results may have fewer labels than the `page_size`. items: title: label type: object description: > A label represents the physical sticker that you affix to a package to ship it. ShipEngine makes it easy for you to [create labels](https://www.shipengine.com/docs/labels/create-a-label/) and then download them in PDF, PNG, or ZPL format so you can print them. additionalProperties: false properties: label_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: > A string that uniquely identifies the label. This ID is generated by ShipEngine when the label is created. status: readOnly: true allOf: - $ref: '#/components/schemas/label_status' shipment_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: > The shipment that this label is for. ShipEngine can create a shipment for you automatically when you [create a label](https://www.shipengine.com/docs/labels/create-a-label/), or you can [create your own shipment](https://www.shipengine.com/docs/shipping/create-a-shipment/) and then [use it to print a label](https://www.shipengine.com/docs/labels/create-from-shipment/) shipment: writeOnly: true allOf: - $ref: '#/components/schemas/shipment' description: The shipment information used to generate the label ship_date: allOf: - $ref: '#/components/schemas/date' readOnly: true description: > The date that the package was (or will be) shippped. ShipEngine will take the day of week into consideration. For example, if the carrier does not operate on Sundays, then a package that would have shipped on Sunday will ship on Monday instead. created_at: readOnly: true allOf: - $ref: '#/components/schemas/date_time' description: The date and time that the label was created in ShipEngine. shipment_cost: readOnly: true allOf: - $ref: '#/components/schemas/monetary_value' description: > The cost of shipping, delivery confirmation, and other carrier charges. This amount **does not** include insurance costs. insurance_cost: readOnly: true allOf: - $ref: '#/components/schemas/monetary_value' description: > The insurance cost for this package. Add this to the `shipment_cost` field to get the total cost. requested_comparison_amount: readOnly: true allOf: - $ref: '#/components/schemas/monetary_value' description: > The total shipping cost for the specified comparison_rate_type. tracking_number: type: string minLength: 1 readOnly: true example: '782758401696' description: >- The tracking number for the package. Tracking number formats vary across carriers. is_return_label: type: boolean description: > Indicates whether this is a return label. You may also want to set the `rma_number` so you know what is being returned. rma_number: type: string nullable: true description: > An optional Return Merchandise Authorization number. This field is useful for return labels. You can set it to any string value. is_international: type: boolean readOnly: true description: > Indicates whether this is an international shipment. That is, the originating country and destination country are different. batch_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: > If this label was created as part of a [batch](https://www.shipengine.com/docs/labels/bulk/), then this is the unique ID of that batch. carrier_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: > The unique ID of the [carrier account](https://www.shipengine.com/docs/carriers/setup/) that was used to create this label charge_event: allOf: - $ref: '#/components/schemas/label_charge_event' description: | The label charge event. outbound_label_id: allOf: - $ref: '#/components/schemas/se_id' writeOnly: true description: > The `label_id` of the original (outgoing) label that the return label is for. This associates the two labels together, which is required by some carriers. service_code: allOf: - $ref: '#/components/schemas/service_code' readOnly: true description: > The [carrier service](https://www.shipengine.com/docs/shipping/use-a-carrier-service/) used to ship the package, such as `fedex_ground`, `usps_first_class_mail`, `flat_rate_envelope`, etc. test_label: writeOnly: true type: boolean default: false deprecated: true description: >- Indicate if this label is being used only for testing purposes. If true, then no charge will be added to your account. package_code: readOnly: true allOf: - $ref: '#/components/schemas/package_code' description: > The [package type](https://www.shipengine.com/docs/reference/list-carrier-packages/), such as `thick_envelope`, `small_flat_rate_box`, `large_package`, etc. The code `package` indicates a custom or unknown package type. validate_address: writeOnly: true default: validate_and_clean allOf: - $ref: '#/components/schemas/validate_address' voided: type: boolean readOnly: true description: > Indicates whether the label has been [voided](https://www.shipengine.com/docs/labels/voiding/) voided_at: nullable: true readOnly: true allOf: - $ref: '#/components/schemas/date_time' description: > The date and time that the label was [voided](https://www.shipengine.com/docs/labels/voiding/), or `null` if the label has not been voided label_download_type: writeOnly: true default: url allOf: - $ref: '#/components/schemas/label_download_type' label_format: default: pdf allOf: - $ref: '#/components/schemas/label_format' description: > The file format that you want the label to be in. We recommend `pdf` format because it is supported by all carriers, whereas some carriers do not support the `png` or `zpl` formats. display_scheme: default: label allOf: - $ref: '#/components/schemas/display_scheme' description: The display format that the label should be shown in. label_layout: default: 4x6 allOf: - $ref: '#/components/schemas/label_layout' description: > The layout (size) that you want the label to be in. The `label_format` determines which sizes are allowed. `4x6` is supported for all label formats, whereas `letter` (8.5" x 11") is only supported for `pdf` format. trackable: type: boolean readOnly: true description: > Indicates whether the shipment is trackable, in which case the `tracking_status` field will reflect the current status and each package will have a `tracking_number`. label_image_id: nullable: true allOf: - $ref: '#/components/schemas/image_id' description: >- The label image resource that was used to create a custom label image. carrier_code: readOnly: true allOf: - $ref: '#/components/schemas/carrier_code' description: > The [shipping carrier](https://www.shipengine.com/docs/carriers/setup/) who will ship the package, such as `fedex`, `dhl_express`, `stamps_com`, etc. tracking_status: readOnly: true allOf: - $ref: '#/components/schemas/tracking_status' description: >- The current status of the package, such as `in_transit` or `delivered` label_download: allOf: - $ref: '#/components/schemas/label_download' readOnly: true form_download: readOnly: true nullable: true allOf: - $ref: '#/components/schemas/link' description: > The link to download the customs form (a.k.a. commercial invoice) for this shipment, if any. Forms are in PDF format. This field is null if the shipment does not require a customs form, or if the carrier does not support it. paperless_download: readOnly: true nullable: true allOf: - $ref: '#/components/schemas/paperless_download' description: > The paperless details which may contain elements like `href`, `instructions` and `handoff_code`. insurance_claim: readOnly: true nullable: true allOf: - $ref: '#/components/schemas/link' description: > The link to submit an insurance claim for the shipment. This field is null if the shipment is not insured or if the insurance provider does not support online claim submission. packages: type: array readOnly: true description: > The label's package(s). > **Note:** Some carriers only allow one package per label. If you attempt to create a multi-package label for a carrier that doesn't allow it, an error will be returned. items: allOf: - $ref: '#/components/schemas/package' - $ref: '#/components/schemas/alternative_identifiers' alternative_identifiers: type: array readOnly: true nullable: true description: > Additional information some carriers may provide by which to identify a given label in their system. items: $ref: '#/components/schemas/alternative_identifier' allOf: - $ref: '#/components/schemas/paged_list_response_body' create_label_request_body: title: create_label_request_body type: object description: A purchase label request body required: - shipment additionalProperties: false allOf: - $ref: '#/components/schemas/label' properties: ship_to_service_point_id: nullable: true type: string description: >- A unique identifier for a carrier service point where the shipment will be delivered by the carrier. This will take precedence over a shipment's ship to address. example: '614940' ship_from_service_point_id: nullable: true type: string description: >- A unique identifier for a carrier drop off point where a merchant plans to deliver packages. This will take precedence over a shipment's ship from address. example: '614940' label: title: label type: object description: > A label represents the physical sticker that you affix to a package to ship it. ShipEngine makes it easy for you to [create labels](https://www.shipengine.com/docs/labels/create-a-label/) and then download them in PDF, PNG, or ZPL format so you can print them. additionalProperties: false properties: label_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: > A string that uniquely identifies the label. This ID is generated by ShipEngine when the label is created. status: readOnly: true allOf: - $ref: '#/components/schemas/label_status' shipment_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: > The shipment that this label is for. ShipEngine can create a shipment for you automatically when you [create a label](https://www.shipengine.com/docs/labels/create-a-label/), or you can [create your own shipment](https://www.shipengine.com/docs/shipping/create-a-shipment/) and then [use it to print a label](https://www.shipengine.com/docs/labels/create-from-shipment/) shipment: writeOnly: true allOf: - $ref: '#/components/schemas/shipment' description: The shipment information used to generate the label ship_date: allOf: - $ref: '#/components/schemas/date' readOnly: true description: > The date that the package was (or will be) shippped. ShipEngine will take the day of week into consideration. For example, if the carrier does not operate on Sundays, then a package that would have shipped on Sunday will ship on Monday instead. created_at: readOnly: true allOf: - $ref: '#/components/schemas/date_time' description: The date and time that the label was created in ShipEngine. shipment_cost: readOnly: true allOf: - $ref: '#/components/schemas/monetary_value' description: > The cost of shipping, delivery confirmation, and other carrier charges. This amount **does not** include insurance costs. insurance_cost: readOnly: true allOf: - $ref: '#/components/schemas/monetary_value' description: > The insurance cost for this package. Add this to the `shipment_cost` field to get the total cost. requested_comparison_amount: readOnly: true allOf: - $ref: '#/components/schemas/monetary_value' description: | The total shipping cost for the specified comparison_rate_type. tracking_number: type: string minLength: 1 readOnly: true example: '782758401696' description: >- The tracking number for the package. Tracking number formats vary across carriers. is_return_label: type: boolean description: > Indicates whether this is a return label. You may also want to set the `rma_number` so you know what is being returned. rma_number: type: string nullable: true description: > An optional Return Merchandise Authorization number. This field is useful for return labels. You can set it to any string value. is_international: type: boolean readOnly: true description: > Indicates whether this is an international shipment. That is, the originating country and destination country are different. batch_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: > If this label was created as part of a [batch](https://www.shipengine.com/docs/labels/bulk/), then this is the unique ID of that batch. carrier_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: > The unique ID of the [carrier account](https://www.shipengine.com/docs/carriers/setup/) that was used to create this label charge_event: allOf: - $ref: '#/components/schemas/label_charge_event' description: | The label charge event. outbound_label_id: allOf: - $ref: '#/components/schemas/se_id' writeOnly: true description: > The `label_id` of the original (outgoing) label that the return label is for. This associates the two labels together, which is required by some carriers. service_code: allOf: - $ref: '#/components/schemas/service_code' readOnly: true description: > The [carrier service](https://www.shipengine.com/docs/shipping/use-a-carrier-service/) used to ship the package, such as `fedex_ground`, `usps_first_class_mail`, `flat_rate_envelope`, etc. test_label: writeOnly: true type: boolean default: false deprecated: true description: >- Indicate if this label is being used only for testing purposes. If true, then no charge will be added to your account. package_code: readOnly: true allOf: - $ref: '#/components/schemas/package_code' description: > The [package type](https://www.shipengine.com/docs/reference/list-carrier-packages/), such as `thick_envelope`, `small_flat_rate_box`, `large_package`, etc. The code `package` indicates a custom or unknown package type. validate_address: writeOnly: true default: validate_and_clean allOf: - $ref: '#/components/schemas/validate_address' voided: type: boolean readOnly: true description: > Indicates whether the label has been [voided](https://www.shipengine.com/docs/labels/voiding/) voided_at: nullable: true readOnly: true allOf: - $ref: '#/components/schemas/date_time' description: > The date and time that the label was [voided](https://www.shipengine.com/docs/labels/voiding/), or `null` if the label has not been voided label_download_type: writeOnly: true default: url allOf: - $ref: '#/components/schemas/label_download_type' label_format: default: pdf allOf: - $ref: '#/components/schemas/label_format' description: > The file format that you want the label to be in. We recommend `pdf` format because it is supported by all carriers, whereas some carriers do not support the `png` or `zpl` formats. display_scheme: default: label allOf: - $ref: '#/components/schemas/display_scheme' description: The display format that the label should be shown in. label_layout: default: 4x6 allOf: - $ref: '#/components/schemas/label_layout' description: > The layout (size) that you want the label to be in. The `label_format` determines which sizes are allowed. `4x6` is supported for all label formats, whereas `letter` (8.5" x 11") is only supported for `pdf` format. trackable: type: boolean readOnly: true description: > Indicates whether the shipment is trackable, in which case the `tracking_status` field will reflect the current status and each package will have a `tracking_number`. label_image_id: nullable: true allOf: - $ref: '#/components/schemas/image_id' description: >- The label image resource that was used to create a custom label image. carrier_code: readOnly: true allOf: - $ref: '#/components/schemas/carrier_code' description: > The [shipping carrier](https://www.shipengine.com/docs/carriers/setup/) who will ship the package, such as `fedex`, `dhl_express`, `stamps_com`, etc. tracking_status: readOnly: true allOf: - $ref: '#/components/schemas/tracking_status' description: >- The current status of the package, such as `in_transit` or `delivered` label_download: allOf: - $ref: '#/components/schemas/label_download' readOnly: true form_download: readOnly: true nullable: true allOf: - $ref: '#/components/schemas/link' description: > The link to download the customs form (a.k.a. commercial invoice) for this shipment, if any. Forms are in PDF format. This field is null if the shipment does not require a customs form, or if the carrier does not support it. paperless_download: readOnly: true nullable: true allOf: - $ref: '#/components/schemas/paperless_download' description: > The paperless details which may contain elements like `href`, `instructions` and `handoff_code`. insurance_claim: readOnly: true nullable: true allOf: - $ref: '#/components/schemas/link' description: > The link to submit an insurance claim for the shipment. This field is null if the shipment is not insured or if the insurance provider does not support online claim submission. packages: type: array readOnly: true description: > The label's package(s). > **Note:** Some carriers only allow one package per label. If you attempt to create a multi-package label for a carrier that doesn't allow it, an error will be returned. items: allOf: - $ref: '#/components/schemas/package' - $ref: '#/components/schemas/alternative_identifiers' alternative_identifiers: type: array readOnly: true nullable: true description: > Additional information some carriers may provide by which to identify a given label in their system. items: $ref: '#/components/schemas/alternative_identifier' shipment: title: shipment type: object description: > The information necessary to ship a package, such as the origin, the destination, the carrier service, and the package dimensions and weight. > **Note:** Either `ship_from` or `warehouse_id` must be set. required: - shipment_id - carrier_id - service_code - ship_date - created_at - modified_at - shipment_status - ship_to - ship_from - warehouse_id - return_to - confirmation - customs - advanced_options - insurance_provider - tags - packages - total_weight additionalProperties: false allOf: - $ref: '#/components/schemas/partial_shipment' partial_shipment: title: partial_shipment type: object description: > The information necessary to ship a package, such as the origin, the destination, the carrier service, and the package dimensions and weight. additionalProperties: false properties: shipment_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the shipment carrier_id: allOf: - $ref: '#/components/schemas/se_id' description: The carrier account that is billed for the shipping charges service_code: allOf: - $ref: '#/components/schemas/service_code' description: > The [carrier service](https://www.shipengine.com/docs/shipping/use-a-carrier-service/) used to ship the package, such as `fedex_ground`, `usps_first_class_mail`, `flat_rate_envelope`, etc. external_order_id: type: string nullable: true description: ID that the Order Source assigned items: type: array default: [] items: allOf: - $ref: '#/components/schemas/shipment_item' description: > Describe the packages included in this shipment as related to potential metadata that was imported from external order sources tax_identifiers: type: array nullable: true items: allOf: - $ref: '#/components/schemas/tax_identifier' external_shipment_id: type: string maxLength: 50 nullable: true description: > A unique user-defined key to identify a shipment. This can be used to retrieve the shipment. > **Warning:** The `external_shipment_id` is limited to 50 characters. Any additional characters will be truncated. shipment_number: type: string maxLength: 50 nullable: true description: > A non-unique user-defined number used to identify a shipment. If undefined, this will match the external_shipment_id of the shipment. > **Warning:** The `shipment_number` is limited to 50 characters. Any additional characters will be truncated. ship_date: allOf: - $ref: '#/components/schemas/date' description: > The date that the shipment was (or will be) shippped. ShipEngine will take the day of week into consideration. For example, if the carrier does not operate on Sundays, then a package that would have shipped on Sunday will ship on Monday instead. created_at: readOnly: true allOf: - $ref: '#/components/schemas/date_time' description: The date and time that the shipment was created in ShipEngine. modified_at: readOnly: true allOf: - $ref: '#/components/schemas/date_time' description: The date and time that the shipment was created or last modified. shipment_status: readOnly: true default: pending allOf: - $ref: '#/components/schemas/shipment_status' description: The current status of the shipment ship_to: allOf: - $ref: '#/components/schemas/shipping_address_to' description: The recipient's mailing address ship_from: allOf: - $ref: '#/components/schemas/shipping_address' description: > The shipment's origin address. If you frequently ship from the same location, consider [creating a warehouse](https://www.shipengine.com/docs/reference/create-warehouse/). Then you can simply specify the `warehouse_id` rather than the complete address each time. warehouse_id: nullable: true default: null allOf: - $ref: '#/components/schemas/se_id' description: > The [warehouse](https://www.shipengine.com/docs/shipping/ship-from-a-warehouse/) that the shipment is being shipped from. Either `warehouse_id` or `ship_from` must be specified. return_to: allOf: - $ref: '#/components/schemas/shipping_address' description: > The return address for this shipment. Defaults to the `ship_from` address. is_return: type: boolean nullable: true default: false description: > An optional indicator if the shipment is intended to be a return. Defaults to false if not provided. confirmation: default: none allOf: - $ref: '#/components/schemas/delivery_confirmation' description: >- The type of delivery confirmation that is required for this shipment. customs: nullable: true default: null allOf: - $ref: '#/components/schemas/international_shipment_options' description: > Customs information. This is usually only needed for international shipments. advanced_options: allOf: - $ref: '#/components/schemas/advanced_shipment_options' description: Advanced shipment options. These are entirely optional. insurance_provider: default: none allOf: - $ref: '#/components/schemas/insurance_provider' description: > The insurance provider to use for any insured packages in the shipment. tags: type: array readOnly: true default: [] minItems: 0 items: allOf: - $ref: '#/components/schemas/tag' description: > Arbitrary tags associated with this shipment. Tags can be used to categorize shipments, and shipments can be queried by their tags. order_source_code: allOf: - $ref: '#/components/schemas/order_source_name' packages: type: array minItems: 1 items: allOf: - $ref: '#/components/schemas/package' description: > The packages in the shipment. > **Note:** Some carriers only allow one package per shipment. If you attempt to create a multi-package shipment for a carrier that doesn't allow it, an error will be returned. total_weight: readOnly: true allOf: - $ref: '#/components/schemas/weight' description: The combined weight of all packages in the shipment comparison_rate_type: nullable: true type: string description: >- Calculate a rate for this shipment with the requested carrier using a ratecard that differs from the default. Only supported for UPS and USPS. example: retail shipment_item: title: shipment_item type: object description: A shipment item additionalProperties: false properties: name: type: string minLength: 0 description: item name sales_order_id: type: string nullable: true description: sales order id sales_order_item_id: type: string nullable: true description: sales order item id quantity: type: integer format: int32 minimum: 0 description: The quantity of this item included in the shipment sku: type: string nullable: true description: Item Stock Keeping Unit external_order_id: type: string nullable: true description: external order id external_order_item_id: type: string nullable: true description: external order item id asin: type: string nullable: true minLength: 10 maxLength: 10 example: B00005N5PF description: Amazon Standard Identification Number order_source_code: allOf: - $ref: '#/components/schemas/order_source_name' order_source_name: title: order_source_name type: string enum: - amazon_ca - amazon_us - brightpearl - channel_advisor - cratejoy - ebay - etsy - jane - groupon_goods - magento - paypal - seller_active - shopify - stitch_labs - squarespace - three_dcart - tophatter - walmart - woo_commerce - volusion description: The order sources that are supported by ShipEngine tax_identifier: title: tax_identifier type: object description: A tax identifier object additionalProperties: false required: - taxable_entity_type - identifier_type - issuing_authority - value properties: taxable_entity_type: allOf: - $ref: '#/components/schemas/taxable_entity_type' identifier_type: allOf: - $ref: '#/components/schemas/identifier_type' issuing_authority: type: string description: >- The authority that issued this tax. This must be a valid 2 character ISO 3166 Alpha 2 country code. value: type: string description: The value of the identifier taxable_entity_type: title: taxable_entity_type type: string enum: - shipper - recipient - ior description: > The taxable entity type for this tax item. Valid values include the following |Value |Description |:--------- |:----------------------------------------------------- |`shipper` | The shipper is responsible for this tax. |`recipient` | The recipient of the shipment is responsible for this tax. |`ior` | The importer of records is responsible for tax. identifier_type: title: identifier_type type: string enum: - vat - eori - ssn - ein - tin - ioss - pan - voec - pccc - oss - passport - abn description: > Tax identifier type for customs declaration |Pickup Type | Description |---------------|----------------------------------------- |`vat` | The tax identifier is a Value Added Tax. |`eori` | The tax identifier is an Economic Operators Registration and Identification Number (EORI). |`ssn` | The tax identifier is a Social Security Number. |`ein` | The tax identifier is an Employer Identification Number (EIN). |`tin` | The tax identifier is a Tax Identification Number (TIN). |`ioss` | The tax identifier is an Import One-Stop Shop (IOSS). |`pan` | The tax identifier is a Permanent Account Number (PAN). |`voec` | The tax identifier is a Norwegian VAT On E-Commerce(VOEC). |`pccc` | The tax identifier is a Personal Customs Clearance Code (PCCC). |`oss` | The tax identifier is an One-Stop Shop (OSS). |`passport` | The tax identifier is a Passport Number. |`abn` | The tax identifier is an Australian Business Number. date: title: date type: string format: date-time pattern: '^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[-+]\d{2}:\d{2}))?$' example: '2018-09-23T00:00:00.000Z' description: > An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that represents a date, but not a specific time. The value _may_ contain a time component, but it will be set to `00:00:00` UTC by ShipEngine. shipment_status: title: shipment_status type: string enum: - pending - processing - label_purchased - cancelled description: The possible shipment status values shipping_address_to: title: shipping_address_to type: object additionalProperties: false allOf: - $ref: '#/components/schemas/address' - $ref: '#/components/schemas/partial_shipping_address_to' partial_shipping_address_to: title: partial_shipping_address_to type: object description: A complete or partial mailing address. additionalProperties: false properties: instructions: type: string minLength: 1 nullable: true description: | Additional text about how to handle the shipment at this address. geolocation: type: array items: type: object properties: type: type: string example: what3words description: | Enum of available type of geolocation items: - 'what3words' functionality allows to specify a location by providing 3 words that have been assign to the specific location see [link](https://what3words.com/business) for more details. enum: - what3words value: type: string example: cats.with.thumbs description: value of the geolocation item shipping_address: title: shipping_address type: object additionalProperties: false allOf: - $ref: '#/components/schemas/address' - $ref: '#/components/schemas/partial_shipping_address' partial_shipping_address: title: partial_shipping_address type: object description: A complete or partial mailing address. additionalProperties: false properties: instructions: type: string minLength: 1 nullable: true description: | Additional text about how to handle the shipment at this address. delivery_confirmation: title: delivery_confirmation type: string enum: - none - delivery - signature - adult_signature - direct_signature - delivery_mailed - verbal_confirmation description: The possible delivery confirmation values international_shipment_options: title: international_shipment_options type: object description: 'Options for international shipments, such as customs declarations.' required: - contents - non_delivery additionalProperties: false properties: contents: default: merchandise allOf: - $ref: '#/components/schemas/package_contents' description: >- The type of contents in this shipment. This may impact import duties or customs treatment. contents_explanation: type: string description: >- Explanation for contents (required if the `contents` is provided as `other`) non_delivery: default: return_to_sender allOf: - $ref: '#/components/schemas/non_delivery' description: Indicates what to do if a package is unable to be delivered. terms_of_trade_code: type: string description: Specifies the supported terms of trade code (incoterms) allOf: - $ref: '#/components/schemas/Allowed incoterms' declaration: type: string description: Declaration statement to be placed on the commercial invoice invoice_additional_details: type: object allOf: - $ref: '#/components/schemas/invoice_additional_details' importer_of_record: type: object allOf: - $ref: '#/components/schemas/importer_of_records' customs_items: deprecated: true type: array default: [] minItems: 0 description: >- Customs declarations for each item in the shipment. (Please provide this information under `products` inside `packages`) items: $ref: '#/components/schemas/customs_item' package_contents: title: package_contents type: string enum: - merchandise - documents - gift - returned_goods - sample - other description: The possible package contents values non_delivery: title: non_delivery type: string enum: - return_to_sender - treat_as_abandoned description: The possible non delivery values Allowed incoterms: title: Allowed incoterms type: string enum: - exw - fca - cpt - cip - dpu - dap - ddp - fas - fob - cfr - cif - ddu - daf - deq - des invoice_additional_details: title: invoice_additional_details type: object description: | The additional information to put on commercial invoice properties: freight_charge: allOf: - $ref: '#/components/schemas/monetary_value' description: Freight Charge for shipment. insurance_charge: allOf: - $ref: '#/components/schemas/monetary_value' description: Insurance Charge for shipment. discount: allOf: - $ref: '#/components/schemas/monetary_value' description: Discount for shipment. other_charge: allOf: - $ref: '#/components/schemas/monetary_value' description: Other charge for shipment. other_charge_description: type: string description: Description for the other charge (if provided). importer_of_records: title: importer_of_records type: object description: | importer of records address, anywhere in the world. required: - name - address_line1 - city_locality - postal_code - country_code properties: name: type: string minLength: 1 example: John Doe description: > The name of a contact person at this address. Either `name` or the `company_name` field should always be set. phone: type: string minLength: 1 example: +1 204-253-9411 ext. 123 description: > The phone number of a contact person at this address. The format of this phone number varies depending on the country. email: type: string nullable: true example: example@example.com description: | Email for the address owner. company_name: type: string minLength: 1 nullable: true example: The Home Depot description: > If this is a business address, then the company name should be specified here. Either `name` or the `company_name` field should always be set. address_line1: type: string minLength: 1 example: 1999 Bishop Grandin Blvd. description: > The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines. address_line2: type: string minLength: 1 nullable: true example: Unit 408 description: > The second line of the street address. For some addresses, this line may not be needed. address_line3: type: string minLength: 1 nullable: true example: 'Building #7' description: > The third line of the street address. For some addresses, this line may not be needed. city_locality: type: string minLength: 1 example: Winnipeg description: The name of the city or locality state_province: type: string minLength: 1 example: Manitoba description: > The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation. postal_code: allOf: - $ref: '#/components/schemas/postal_code' country_code: allOf: - $ref: '#/components/schemas/country_code' description: > The two-letter [ISO 3166-1 country code](https://en.wikipedia.org/wiki/ISO_3166-1) customs_item: title: customs_item type: object description: The customs declaration for a single item in the shipment. required: - customs_item_id additionalProperties: false properties: customs_item_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the customs item description: type: string nullable: true maxLength: 100 default: null description: A description of the item quantity: type: integer format: int32 minimum: 0 default: 0 description: The quantity of this item in the shipment. value: type: number format: double minimum: 0 description: 'The monetary amount, in the specified currency.' value_currency: type: string description: > The currencies that are supported by ShipEngine are the ones that specified by ISO 4217: https://www.iso.org/iso-4217-currency-codes.html weight: allOf: - $ref: '#/components/schemas/weight' description: The item weight harmonized_tariff_code: type: string nullable: true default: null example: 3926.1 description: >- The [Harmonized Tariff Code](https://en.wikipedia.org/wiki/Harmonized_System) of this item. country_of_origin: nullable: true default: null allOf: - $ref: '#/components/schemas/country_code' description: > The two-letter [ISO 3166-1 country code](https://en.wikipedia.org/wiki/ISO_3166-1) where this item originated unit_of_measure: type: string nullable: true sku: type: string description: The SKU (Stock Keeping Unit) of the customs item nullable: true sku_description: type: string description: Description of the Custom Item's SKU nullable: true weight: title: weight type: object description: The weight of a package required: - value - unit additionalProperties: false properties: value: type: number format: double minimum: 0 exclusiveMinimum: true description: 'The weight, in the specified unit' unit: allOf: - $ref: '#/components/schemas/weight_unit' weight_unit: title: weight_unit type: string enum: - pound - ounce - gram - kilogram description: The possible weight unit values advanced_shipment_options: title: advanced_shipment_options type: object description: Advanced shipment options additionalProperties: false properties: bill_to_account: type: string nullable: true default: null description: > This field is used to [bill shipping costs to a third party](https://www.shipengine.com/docs/shipping/bill-to-third-party/). This field must be used in conjunction with the `bill_to_country_code`, `bill_to_party`, and `bill_to_postal_code` fields. bill_to_country_code: nullable: true default: null allOf: - $ref: '#/components/schemas/country_code' description: > The two-letter [ISO 3166-1 country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the third-party that is responsible for shipping costs. bill_to_party: nullable: true default: null allOf: - $ref: '#/components/schemas/bill_to_party' description: > Indicates whether to bill shipping costs to the recipient or to a third-party. When billing to a third-party, the `bill_to_account`, `bill_to_country_code`, and `bill_to_postal_code` fields must also be set. bill_to_postal_code: type: string nullable: true default: null description: > The postal code of the third-party that is responsible for shipping costs. contains_alcohol: type: boolean default: false description: Indicates that the shipment contains alcohol. delivered_duty_paid: type: boolean default: false description: > Indicates that the shipper is paying the international delivery duties for this shipment. This option is supported by UPS, FedEx, and DHL Express. dry_ice: type: boolean default: false description: Indicates if the shipment contain dry ice dry_ice_weight: nullable: true allOf: - $ref: '#/components/schemas/weight' description: The weight of the dry ice in the shipment non_machinable: type: boolean default: false description: > Indicates that the package cannot be processed automatically because it is too large or irregularly shaped. This is primarily for USPS shipments. See [Section 1.2 of the USPS parcel standards](https://pe.usps.com/text/dmm300/101.htm#ep1047495) for details. saturday_delivery: type: boolean default: false description: 'Enables Saturday delivery, if supported by the carrier.' fedex_freight: type: object description: Provide details for the Fedex freight service properties: shipper_load_and_count: type: string booking_confirmation: type: string use_ups_ground_freight_pricing: type: boolean nullable: true default: null description: > Whether to use [UPS Ground Freight pricing](https://www.shipengine.com/docs/shipping/ups-ground-freight/). If enabled, then a `freight_class` must also be specified. freight_class: type: string nullable: true default: null example: 77.5 description: > The National Motor Freight Traffic Association [freight class](http://www.nmfta.org/pages/nmfc?AspxAutoDetectCookieSupport=1), such as "77.5", "110", or "250". custom_field1: type: string nullable: true default: null maxLength: 100 description: > An arbitrary field that can be used to store information about the shipment. custom_field2: type: string nullable: true default: null maxLength: 100 description: > An arbitrary field that can be used to store information about the shipment. custom_field3: type: string nullable: true default: null maxLength: 100 description: > An arbitrary field that can be used to store information about the shipment. origin_type: nullable: true default: null allOf: - $ref: '#/components/schemas/origin_type' additional_handling: type: boolean nullable: true default: null description: > Indicate to the carrier that this shipment requires additional handling. shipper_release: type: boolean nullable: true default: null collect_on_delivery: $ref: '#/components/schemas/collect_on_delivery' third_party_consignee: type: boolean default: false description: >- Third Party Consignee option is a value-added service that allows the shipper to supply goods without commercial invoices being attached dangerous_goods: type: boolean default: false description: Indicates if the Dangerous goods are present in the shipment dangerous_goods_contact: type: object description: Contact information for Dangerous goods properties: name: type: string description: Name of the contact phone: type: string description: Phone number of the contact bill_to_party: title: bill_to_party type: string enum: - recipient - third_party description: The possible bill to party values origin_type: title: origin_type type: string enum: - pickup - drop_off description: Indicates if the package will be picked up or dropped off by the carrier collect_on_delivery: title: collect_on_delivery type: object description: 'Defer payment until package is delivered, instead of when it is ordered.' properties: payment_type: allOf: - $ref: '#/components/schemas/collect_on_delivery_payment_type' payment_amount: $ref: '#/components/schemas/payment_amount' collect_on_delivery_payment_type: title: collect_on_delivery_payment_type type: string enum: - any - cash - cash_equivalent - none description: Types of payment that are supported payment_amount: title: payment_amount type: object properties: currency: allOf: - $ref: '#/components/schemas/currency' amount: minimum: 0 format: double type: number insurance_provider: title: insurance_provider type: string enum: - none - shipsurance - carrier - third_party description: The possible insurance provider values tag: title: tag type: object description: > Tags are arbitrary strings that you can use to categorize shipments. For example, you may want to use tags to distinguish between domestic and international shipments, or between insured and uninsured shipments. Or maybe you want to create a tag for each of your customers so you can easily retrieve every shipment for a customer. required: - name additionalProperties: false properties: name: type: string minLength: 1 example: Fragile description: The tag name. package: title: package type: object description: > A package associated with a [shipping label](https://www.shipengine.com/docs/labels/create-a-label/) required: - weight additionalProperties: false properties: package_id: allOf: - $ref: '#/components/schemas/se_id' description: >- A string that uniquely identifies this [package type](https://www.shipengine.com/docs/reference/list-carrier-packages/) package_code: allOf: - $ref: '#/components/schemas/package_code' description: > The [package type](https://www.shipengine.com/docs/reference/list-carrier-packages/), such as `thick_envelope`, `small_flat_rate_box`, `large_package`, etc. The code `package` indicates a custom or unknown package type. content_description: type: string minLength: 1 maxLength: 35 description: > A short description of the package content. Required for shipments moving to, from, and through Mexico. example: Hand knitted wool socks nullable: true weight: allOf: - $ref: '#/components/schemas/weight' description: The package weight dimensions: allOf: - $ref: '#/components/schemas/dimensions' description: The package dimensions insured_value: allOf: - $ref: '#/components/schemas/monetary_value' default: - currency: usd amount: 0 description: > The insured value of the package. Requires the `insurance_provider` field of the shipment to be set. tracking_number: readOnly: true allOf: - $ref: '#/components/schemas/tracking_number' description: > The tracking number for the package. The format depends on the carrier. label_messages: allOf: - $ref: '#/components/schemas/label_messages' external_package_id: type: string minLength: 1 description: An external package id. label_download: readOnly: true allOf: - $ref: '#/components/schemas/label_download' description: The label download for the package form_download: readOnly: true allOf: - $ref: '#/components/schemas/optional_link' description: The form download for any customs that are needed paperless_download: readOnly: true allOf: - $ref: '#/components/schemas/paperless_download' description: >- The paperless details which may contain elements like `href`, `instructions` and `handoff_code`. sequence: readOnly: true format: int32 type: integer description: Package sequence products: type: array default: [] minItems: 0 description: >- Details about products inside packages (Information provided would be used on custom documentation) items: $ref: '#/components/schemas/products' tracking_number: title: tracking_number type: string minLength: 1 example: 1Z932R800392060079 description: A tracking number for a package. The format depends on the carrier. label_messages: title: label_messages type: object description: > Custom messages to print on the shipping label for the package. These are typically used to print invoice numbers, product numbers, or other internal reference numbers. Not all carriers support label messages. The number of lines and the maximum length of each line also varies by carrier. |Carrier |Max lines |Max line length |-------------------|----------|-------------------- |USPS (Stamps.com) |3 |60 |FedEx |3 |35 for the first line. 30 for additional lines. |UPS |2 |35 |OnTrac |2 |25 required: - reference1 - reference2 - reference3 additionalProperties: false properties: reference1: type: string nullable: true default: null description: > The first line of the custom label message. Some carriers may prefix this line with something like "REF", "Reference", "Trx Ref No.", etc. reference2: type: string nullable: true default: null description: > The second line of the custom label message. Some carriers may prefix this line with something like "INV", "Reference 2", "Trx Ref No.", etc. reference3: type: string nullable: true default: null description: > The third line of the custom label message. Some carriers may prefix this line with something like "PO", "Reference 3", etc. products: title: products type: object description: The customs declaration for a single item in the shipment. additionalProperties: false properties: description: type: string nullable: true maxLength: 100 default: null description: A description of the item quantity: type: integer format: int32 minimum: 0 default: 0 description: The quantity of this item in the shipment. value: allOf: - $ref: '#/components/schemas/monetary_value' description: The declared value of each item weight: allOf: - $ref: '#/components/schemas/weight' description: The item weight harmonized_tariff_code: type: string nullable: true default: null example: 3926.1 description: >- The [Harmonized Tariff Code](https://en.wikipedia.org/wiki/Harmonized_System) of this item. country_of_origin: nullable: true default: null allOf: - $ref: '#/components/schemas/country_code' description: > The two-letter [ISO 3166-1 country code](https://en.wikipedia.org/wiki/ISO_3166-1) where this item originated unit_of_measure: type: string nullable: true sku: type: string description: The SKU (Stock Keeping Unit) of the item nullable: true sku_description: type: string description: Description of the Custom Item's SKU nullable: true mid_code: type: string description: Manufacturers Identification code nullable: true product_url: type: string description: link to the item on the seller website nullable: true vat_rate: type: number format: double description: VAT rate applicable to the item nullable: true example: 0.2 dangerous_goods: type: array default: [] minItems: 0 description: Details about dangerous goods inside products items: $ref: '#/components/schemas/dangerous_goods' dangerous_goods: title: dangerous_goods type: object description: | Dangerous goods attribute associated with the product additionalProperties: false properties: id_number: type: string nullable: true default: null description: UN number to identify the dangerous goods. shipping_name: type: string nullable: true default: null description: Trade description of the dangerous goods. technical_name: type: string nullable: true default: null description: Recognized Technical or chemical name of dangerous goods. product_class: type: string nullable: true default: null description: Dangerous goods product class based on regulation. product_class_subsidiary: type: string nullable: true default: null description: >- A secondary of product class for substances presenting more than one particular hazard packaging_group: $ref: '#/components/schemas/packaging_group' dangerous_amount: allOf: - $ref: '#/components/schemas/dangerous_amount' description: This model represents the amount of the dangerous goods. quantity: type: integer format: int32 minimum: 0 default: 0 description: Quantity of dangerous goods. packaging_instruction: type: string nullable: true default: null description: >- The specific standardized packaging instructions from the relevant regulatory agency that have been applied to the parcel/container. packaging_instruction_section: $ref: '#/components/schemas/packaging_instruction_section' packaging_type: type: string nullable: true default: null description: The type of exterior packaging used to contain the dangerous good. transport_mean: $ref: '#/components/schemas/transport_mean' transport_category: type: string nullable: true default: null description: >- Transport category assign to dangerous goods for the transport purpose. regulation_authority: type: string nullable: true default: null description: Name of the regulatory authority. regulation_level: $ref: '#/components/schemas/regulation_level' radioactive: type: boolean nullable: true example: false description: Indication if the substance is radioactive. reportable_quantity: type: boolean nullable: true example: false description: >- Indication if the substance needs to be reported to regulatory authority based on the quantity. tunnel_code: type: string nullable: true default: null description: Defines which types of tunnels the shipment is allowed to go through additional_description: type: string nullable: true default: null description: >- Provider additonal description regarding the dangerous goods. This is used as a placed holder to provider additional context and varies by carrier packaging_group: title: packaging_group type: string enum: - i - ii - iii dangerous_amount: title: dangerous_amount type: object description: This model represents the amount of the dangerous goods.. additionalProperties: false properties: amount: type: integer format: int32 minimum: 0 default: 0 description: The amount of dangerous goods. unit: type: string nullable: true default: null description: The unit of dangerous goods. packaging_instruction_section: title: packaging_instruction_section type: string enum: - section_1 - section_2 - section_1a - section_1b transport_mean: title: transport_mean type: string enum: - ground - water - cargo_aircraft_only - passenger_aircraft regulation_level: title: regulation_level type: string enum: - lightly_regulated - fully_regulated - limited_quantities - excepted_quantity label_charge_event: title: label_charge_event type: string enum: - carrier_default - on_creation - on_carrier_acceptance description: Determines when the user's account will be charged for the label. validate_address: title: validate_address type: string enum: - no_validation - validate_only - validate_and_clean description: The possible validate address values label_download_type: title: label_download_type type: string enum: - url - inline description: > There are two different ways to [download a label](https://www.shipengine.com/docs/labels/downloading/): |Label Download Type | Description |--------------------|------------------------------ |`url` |You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.

This is the default if `label_download_type` is unspecified. |`inline` |You will receive the Base64-encoded label as part of the response. No need for a second request to download the label. tracking_status: title: tracking_status type: string enum: - unknown - in_transit - error - delivered description: The different statuses that can apply to a shipment. alternative_identifiers: title: alternative_identifiers type: object additionalProperties: false properties: alternative_identifiers: type: array readOnly: true nullable: true description: | Alternative identifiers associated with this package. items: $ref: '#/components/schemas/alternative_identifier' alternative_identifier: title: alternative_identifier type: object description: > Additional information some carriers may provide by which to identify a given label in their system. additionalProperties: false properties: type: type: string minLength: 1 example: last_mile_tracking_number description: | The type of alternative_identifier that corresponds to the value. value: type: string minLength: 1 example: '12345678912345678912' description: | The value of the alternative_identifier. create_label_response_body: title: create_label_response_body type: object description: A create label response body additionalProperties: false required: - label_id - status - shipment_id - ship_date - created_at - shipment_cost - insurance_cost - tracking_number - is_international - batch_id - carrier_id - service_code - voided - voided_at - label_image_id - label_format - label_layout - trackable - carrier_code - tracking_status - label_download - form_download - paperless_download - insurance_claim - packages - is_return_label - rma_number - charge_event - package_code - display_scheme allOf: - $ref: '#/components/schemas/label' get_label_by_external_shipment_id_response_body: title: get_label_by_external_shipment_id_response_body type: object description: A get label by external shipment id response body additionalProperties: false allOf: - $ref: '#/components/schemas/label' create_label_from_rate_request_body: title: create_label_from_rate_request_body type: object description: A purchase label without shipment request body additionalProperties: false allOf: - $ref: '#/components/schemas/purchase_label_without_shipment' purchase_label_without_shipment: title: purchase_label_without_shipment type: object description: A purchase label without shipment resource additionalProperties: false properties: validate_address: allOf: - $ref: '#/components/schemas/validate_address' label_layout: default: 4x6 allOf: - $ref: '#/components/schemas/label_layout' label_format: default: pdf allOf: - $ref: '#/components/schemas/label_format' label_download_type: allOf: - $ref: '#/components/schemas/label_download_type' display_scheme: default: label allOf: - $ref: '#/components/schemas/display_scheme' description: The display format that the label should be shown in. create_label_from_rate_response_body: title: create_label_from_rate_response_body type: object description: A create label from rate response body additionalProperties: false allOf: - $ref: '#/components/schemas/label' create_label_from_shipment_request_body: title: create_label_from_shipment_request_body type: object description: A purchase label without shipment request body additionalProperties: false properties: validate_address: allOf: - $ref: '#/components/schemas/validate_address' label_layout: default: 4x6 allOf: - $ref: '#/components/schemas/label_layout' label_format: default: pdf allOf: - $ref: '#/components/schemas/label_format' label_download_type: allOf: - $ref: '#/components/schemas/label_download_type' display_scheme: default: label allOf: - $ref: '#/components/schemas/display_scheme' description: The display format that the label should be shown in. create_label_from_shipment_response_body: title: create_label_from_shipment_response_body type: object description: A create label from shipment response body additionalProperties: false allOf: - $ref: '#/components/schemas/label' get_label_by_id_response_body: title: get_label_by_id_response_body type: object description: A get label by id response body additionalProperties: false allOf: - $ref: '#/components/schemas/label' create_return_label_request_body: title: create_return_label_request_body type: object description: A create return label request body additionalProperties: false properties: charge_event: allOf: - $ref: '#/components/schemas/label_charge_event' description: | The label charge event. label_layout: default: 4x6 allOf: - $ref: '#/components/schemas/label_layout' description: > The layout (size) that you want the label to be in. The `label_format` determines which sizes are allowed. `4x6` is supported for all label formats, whereas `letter` (8.5" x 11") is only supported for `pdf` format. label_format: default: pdf allOf: - $ref: '#/components/schemas/label_format' description: > The file format that you want the label to be in. We recommend `pdf` format because it is supported by all carriers, whereas some carriers do not support the `png` or `zpl` formats. label_download_type: writeOnly: true default: url allOf: - $ref: '#/components/schemas/label_download_type' display_scheme: default: label allOf: - $ref: '#/components/schemas/display_scheme' description: The display format that the label should be shown in. label_image_id: nullable: true allOf: - $ref: '#/components/schemas/image_id' description: >- The label image resource that was used to create a custom label image. create_return_label_response_body: title: create_return_label_response_body type: object description: A create return label response body additionalProperties: false allOf: - $ref: '#/components/schemas/label' get_tracking_log_from_label_response_body: title: get_tracking_log_from_label_response_body type: object description: A get tracking log from label response body required: - tracking_number - status_code - carrier_status_code - estimated_delivery_date - events additionalProperties: false allOf: - $ref: '#/components/schemas/tracking_information' tracking_information: title: tracking_information type: object description: A tracking information resource additionalProperties: false properties: tracking_number: allOf: - $ref: '#/components/schemas/tracking_number' tracking_url: type: string readOnly: true example: 'https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234' description: 'Carrier Tracking Url, if available' status_code: allOf: - $ref: '#/components/schemas/status_code' carrier_code: allOf: - $ref: '#/components/schemas/carrier_code' carrier_id: allOf: - $ref: '#/components/schemas/se_id' status_description: type: string readOnly: true example: Delivered minLength: 0 description: Status description carrier_status_code: type: string readOnly: true minLength: 1 example: 1 description: Carrier status code carrier_detail_code: type: string readOnly: true minLength: 1 example: OT description: Carrier detail code carrier_status_description: type: string minLength: 0 readOnly: true example: 'Your item was delivered in or at the mailbox at 9:10 am on March' description: carrier status description ship_date: allOf: - $ref: '#/components/schemas/date_time' estimated_delivery_date: allOf: - $ref: '#/components/schemas/date_time' actual_delivery_date: allOf: - $ref: '#/components/schemas/date_time' exception_description: type: string readOnly: true minLength: 0 description: Exception description events: type: array readOnly: true items: $ref: '#/components/schemas/track_event' description: >- The events that have occured during the lifetime of this tracking number. status_code: readOnly: true title: status_code enum: - un - ac - it - de - ex - at - ny type: string description: | The tracking status codes |Value |Description |:--------- |:----------------------------------------------------- |`un` | Unknown |`ac` | Accepted |`it` | In Transit |`de` | Delivered |`ex` | Exception |`at` | Delivery Attempt |`ny` | Not Yet In System track_event: title: track_event type: object description: A track event required: - occurred_at - city_locality - state_province - postal_code - carrier_detail_code - status_code - status_description - carrier_status_code - carrier_status_description additionalProperties: false properties: occurred_at: allOf: - $ref: '#/components/schemas/date_time' description: Timestamp for carrier event carrier_occurred_at: allOf: - $ref: '#/components/schemas/date_time' description: >- Carrier timestamp for the event, it is assumed to be the local time of where the event occurred. description: type: string readOnly: true minLength: 0 example: 'Delivered, In/At Mailbox' description: Event description city_locality: type: string readOnly: true example: AUSTIN minLength: 0 description: City locality state_province: type: string readOnly: true example: TX minLength: 2 description: State province postal_code: type: string readOnly: true example: 78756 minLength: 0 description: Postal code country_code: allOf: - $ref: '#/components/schemas/country_code' company_name: type: string readOnly: true example: Stamps.com minLength: 0 description: Company Name signer: type: string minLength: 0 readOnly: true description: Signer information event_code: type: string minLength: 0 description: Event Code carrier_detail_code: type: string readOnly: true minLength: 1 example: OT description: Carrier detail code status_code: allOf: - $ref: '#/components/schemas/status_code' status_description: type: string readOnly: true minLength: 1 example: In Transit description: Event Status Description carrier_status_code: type: string readOnly: true minLength: 1 example: 1 description: Carrier status code carrier_status_description: type: string minLength: 0 readOnly: true example: 'Your item was delivered in or at the mailbox at 9:10 am on March' description: carrier status description latitude: type: number format: double minimum: -90 maximum: 90 description: Latitude coordinate of tracking event. longitude: type: number format: double minimum: -180 maximum: 180 description: Longitude coordinate of tracking event. void_label_response_body: title: void_label_response_body type: object description: A void label response body required: - approved - message additionalProperties: false properties: approved: type: boolean readOnly: true example: false description: Indicates whether the attempt to void the label was successful message: type: string minLength: 0 readOnly: true example: >- Unable to delete FedEx shipment. Unable to retrieve record from database. reason_code: readOnly: true type: string allOf: - $ref: '#/components/schemas/reason_code' description: >- Indicates a normalized reason for the conditions if the void attempt was not approved. Will not populate if approved is true. “unknown” codes may be specified later. example: label_not_found_within_void_period reason_code: title: reason_code type: string enum: - unknown - unspecified - validation_failed - label_not_found_within_void_period - label_already_used - label_already_voided - contact_carrier description: >- The possible normalized reasons a label void request may not have been approved list_manifests_response_body: title: list_manifests_response_body type: object description: A list manifests response body required: - manifests - total - page - pages - links additionalProperties: false properties: manifests: type: array readOnly: true default: [] items: readOnly: true allOf: - $ref: '#/components/schemas/manifest' description: A single manifest description: The list of available manifests total: type: integer format: int64 readOnly: true minimum: 0 example: 3 description: The total number of manifests returned page: type: integer format: int32 readOnly: true minimum: 1 example: 3 description: Current page of the list manifests results pages: type: integer format: int32 readOnly: true minimum: 1 example: 4 description: Total number of pages for list manifests results links: readOnly: true allOf: - $ref: '#/components/schemas/pagination_link' description: Helpful links to other pages of results manifest: title: manifest type: object description: > Used for combining packages into one scannable form that a carrier can use when picking up a large number of shipments additionalProperties: false properties: manifest_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the manifest form_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the form created_at: type: string format: date-time minLength: 1 readOnly: true example: '2019-07-12T13:37:39.050Z' description: The date-time that the manifest was created ship_date: type: string format: date-time minLength: 1 readOnly: true example: '2019-07-12T13:37:39.050Z' description: The date-time that the manifests shipments will be picked up shipments: type: integer format: int32 readOnly: true minimum: 1 example: 100 description: The number of shipments that are included in this manifest label_ids: type: array readOnly: true items: allOf: - $ref: '#/components/schemas/se_id' description: An array of the label ids used in this manifest. warehouse_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the warehouse submission_id: readOnly: true type: string minLength: 1 example: '9475711899564878915476' description: A string that uniquely identifies the submission carrier_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the carrier manifest_download: readOnly: true allOf: - $ref: '#/components/schemas/manifest_download' manifest_download: title: manifest_download type: object description: Object containing the href link to download the manifest file additionalProperties: false properties: href: allOf: - $ref: '#/components/schemas/url' description: 'The URL of the linked resource, if any' create_manifest_request_body: title: create_manifest_request_body oneOf: - $ref: '#/components/schemas/create_manifest_by_object_request_body' - $ref: '#/components/schemas/create_manifest_label_ids_request_body' create_manifest_by_object_request_body: title: create_manifest_by_object_request_body type: object description: A create manifest request body required: - carrier_id - warehouse_id - ship_date additionalProperties: false properties: carrier_id: allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the carrier excluded_label_ids: type: array items: allOf: - $ref: '#/components/schemas/se_id' description: Label Id that will be excluded from the manifest description: The list of label ids to exclude from the manifest label_ids: type: array items: allOf: - $ref: '#/components/schemas/se_id' description: Label Id that will be included for the manifest description: The list of label ids to include for the manifest warehouse_id: allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the warehouse ship_date: type: string format: date-time minLength: 1 example: '2018-09-23T15:00:00.000Z' description: The ship date that the shipment will be sent out on create_manifest_label_ids_request_body: title: create_manifest_label_ids_request_body type: object description: A create manifest request body required: - label_ids additionalProperties: false properties: label_ids: type: array items: allOf: - $ref: '#/components/schemas/se_id' description: Label Id that will be included in the manifest description: The list of label ids to include in the manifest create_manifest_response_body: title: create_manifest_response_body type: object description: A create manifest response body required: - manifest_id - form_id - created_at - ship_date - shipments - warehouse_id - submission_id - carrier_id - manifest_download additionalProperties: false allOf: - $ref: '#/components/schemas/manifests' - $ref: '#/components/schemas/manifests_requests' - $ref: '#/components/schemas/deprecated_manifest' - $ref: '#/components/schemas/error_with_label_id_response_body' manifests: title: manifests type: object description: An array of manifest resources additionalProperties: false properties: manifests: description: Resulting Manifests type: array items: $ref: '#/components/schemas/manifest' manifests_requests: title: manifests_requests type: object description: An array of manifest requests additionalProperties: false properties: manifest_requests: description: Resulting manifest requests with statuses type: array items: $ref: '#/components/schemas/manifest_request' manifest_request: title: manifest_request type: object description: A reference to the manifest request additionalProperties: false properties: manifest_request_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies a manifest request status: allOf: - $ref: '#/components/schemas/manifest_request_status' manifest_request_status: title: manifest_request_status type: string enum: - in_progress - completed description: The possible statuses of a manifest request deprecated_manifest: title: deprecated_manifest type: object description: Deprecated manifest resource additionalProperties: false properties: manifest_id: deprecated: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the manifest form_id: deprecated: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the form created_at: deprecated: true type: string format: date-time minLength: 1 example: '2019-07-12T13:37:39.050Z' description: The date-time that the manifest was created ship_date: deprecated: true type: string format: date-time minLength: 1 example: '2019-07-12T13:37:39.050Z' description: The date-time that the manifests shipments will be picked up shipments: deprecated: true type: integer format: int32 readOnly: true minimum: 1 example: 100 description: The number of shipments that are included in this manifest warehouse_id: deprecated: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the warehouse submission_id: deprecated: true type: string minLength: 1 example: '9475711899564878915476' description: A string that uniquely identifies the submission carrier_id: deprecated: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the carrier manifest_download: deprecated: true allOf: - $ref: '#/components/schemas/manifest_download' label_ids: deprecated: true type: array readOnly: true items: allOf: - $ref: '#/components/schemas/se_id' description: An array of the label ids used in this manifest. error_with_label_id_response_body: title: error_with_label_id_response_body type: object description: An error response body required: - request_id - errors additionalProperties: false properties: request_id: allOf: - $ref: '#/components/schemas/uuid' description: > A UUID that uniquely identifies the request id. This can be given to the support team to help debug non-trivial issues that may occur errors: type: array readOnly: true items: allOf: - $ref: '#/components/schemas/error' description: The errors associated with the failed API call get_manifest_by_id_response_body: title: get_manifest_by_id_response_body type: object description: A get manifest by id response body required: - manifest_id - form_id - created_at - ship_date - shipments - warehouse_id - submission_id - carrier_id - manifest_download - label_ids additionalProperties: false allOf: - $ref: '#/components/schemas/manifest' list_package_types_response_body: title: list_package_types_response_body type: object description: A list package types response body additionalProperties: false properties: packages: type: array readOnly: true items: readOnly: true allOf: - $ref: '#/components/schemas/package_type' description: Custom Package Types items description: An array of custom package types create_package_type_request_body: title: create_package_type_request_body type: object description: A create package type request body additionalProperties: false allOf: - $ref: '#/components/schemas/package_type' create_package_type_response_body: title: create_package_type_response_body type: object description: A create package type response body additionalProperties: false allOf: - $ref: '#/components/schemas/package_type' get_package_type_by_id_response_body: title: get_package_type_by_id_response_body type: object description: A get package type by id response body additionalProperties: false allOf: - $ref: '#/components/schemas/package_type' update_package_type_request_body: title: update_package_type_request_body type: object description: An update package type request body additionalProperties: false allOf: - $ref: '#/components/schemas/package_type' get_pickups_response_body: title: get_pickups_response_body allOf: - $ref: '#/components/schemas/list_pickup_response_body' - $ref: '#/components/schemas/error_response_body' list_pickup_response_body: title: list_pickup_response_body type: object description: A list pickup response body required: - pickups - total - page - pages - links additionalProperties: false properties: pickups: type: array description: An array of pickups associated with the user's account. items: allOf: - $ref: '#/components/schemas/pickup' total: type: integer format: int64 readOnly: true minimum: 0 example: 3 description: The total number of pickups returned page: type: integer format: int32 readOnly: true minimum: 1 example: 3 description: Current page of the list pickups results pages: type: integer format: int32 readOnly: true minimum: 1 example: 4 description: Total number of pages for list pickups results links: readOnly: true allOf: - $ref: '#/components/schemas/pagination_link' description: Helpful links to other pages of results pickup: title: pickup type: object description: | The information necessary to schedule a package pickup additionalProperties: false properties: pickup_id: readOnly: true allOf: - $ref: '#/components/schemas/pickup_resource_id' label_ids: type: array items: allOf: - $ref: '#/components/schemas/se_id' description: Label ID that will be included in the pickup request description: Label IDs that will be included in the pickup request created_at: readOnly: true allOf: - $ref: '#/components/schemas/date_time' description: The date and time that the pickup was created in ShipEngine. cancelled_at: readOnly: true allOf: - $ref: '#/components/schemas/date_time' description: The date and time that the pickup was cancelled in ShipEngine. carrier_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: The carrier_id associated with the pickup confirmation_number: readOnly: true type: string nullable: true description: The carrier confirmation number for the scheduled pickup. example: 292513CL4A3 warehouse_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: The warehouse_id associated with the pickup pickup_address: readOnly: true allOf: - $ref: '#/components/schemas/address' contact_details: $ref: '#/components/schemas/contact_details' pickup_notes: type: string minLength: 0 description: >- Used by some carriers to give special instructions for a package pickup pickup_window: $ref: '#/components/schemas/pickup_window' pickup_windows: readOnly: true type: array description: > An array of available pickup windows. Carriers can return multiple times that they will pickup packages. items: allOf: - $ref: '#/components/schemas/pickup_windows' pickup_resource_id: title: pickup_resource_id type: string minLength: 4 example: pik_3YcKU5zdtJuCqoeNwyqqbW description: Pickup Resource ID contact_details: title: contact_details type: object required: - name - email - phone properties: name: type: string minLength: 1 email: allOf: - $ref: '#/components/schemas/email' phone: type: string minLength: 7 description: Phone number associated pickup_window: title: pickup_window writeOnly: true type: object description: The desired time range for the package pickup. required: - start_at - end_at properties: start_at: allOf: - $ref: '#/components/schemas/date_time' end_at: allOf: - $ref: '#/components/schemas/date_time' pickup_windows: title: pickup_windows type: object properties: start_at: allOf: - $ref: '#/components/schemas/date_time' end_at: allOf: - $ref: '#/components/schemas/date_time' schedule_pickup_request_body: title: schedule_pickup_request_body type: object description: A schedule pickup request body required: - contact_details - label_ids - pickup_window additionalProperties: false allOf: - $ref: '#/components/schemas/pickup' schedule_pickup_response_body: title: schedule_pickup_response_body allOf: - $ref: '#/components/schemas/pickup' - $ref: '#/components/schemas/error_response_body' get_pickup_by_id_response_body: title: get_pickup_by_id_response_body allOf: - $ref: '#/components/schemas/pickup_response_body' - $ref: '#/components/schemas/error_response_body' pickup_response_body: title: pickup_response_body type: object description: A pickup response body required: - pickup - pickup_id - label_ids - created_at - carrier_id - warehouse_id - pickup_address - contact_details - notes - pickup_window - confirmation_number additionalProperties: false allOf: - $ref: '#/components/schemas/pickup' delete_pickup_by_id_response_body: title: delete_pickup_by_id_response_body allOf: - $ref: '#/components/schemas/error_response_body' - $ref: '#/components/schemas/delete_scheduled_pickup_response_body' delete_scheduled_pickup_response_body: title: delete_scheduled_pickup_response_body type: object description: A delete scheduled pickup response body additionalProperties: false required: - pickup_id properties: pickup_id: allOf: - $ref: '#/components/schemas/pickup_resource_id' calculate_rates_request_body: title: calculate_rates_request_body type: object description: A rate shipment request body required: - shipment_id - shipment additionalProperties: false oneOf: - $ref: '#/components/schemas/shipment_id_request' - $ref: '#/components/schemas/shipment_request' allOf: - $ref: '#/components/schemas/rate_request_options' shipment_id_request: title: shipment_id_request type: object properties: shipment_id: allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the shipment shipment_request: title: shipment_request type: object properties: shipment: allOf: - $ref: '#/components/schemas/address_validating_shipment' description: The shipment object address_validating_shipment: title: address_validating_shipment type: object description: An address validating shipment required: - shipment_id - carrier_id - service_code - ship_to - ship_from additionalProperties: false allOf: - $ref: '#/components/schemas/validate_shipment_fields' - $ref: '#/components/schemas/partial_shipment' validate_shipment_fields: title: validate_shipment_fields type: object properties: validate_address: default: no_validation allOf: - $ref: '#/components/schemas/validate_address' rate_request_options: title: rate_request_options type: object properties: rate_options: allOf: - $ref: '#/components/schemas/rate_request_body' description: The rate options rate_request_body: title: rate_request_body type: object description: A rate request body required: - carrier_ids additionalProperties: false properties: carrier_ids: type: array minItems: 1 items: allOf: - $ref: '#/components/schemas/se_id' description: carrier ids description: Array of carrier ids to get rates for package_types: type: array items: type: string minLength: 1 service_codes: type: array items: type: string minLength: 1 description: Item Service Codes calculate_tax_amount: type: boolean description: Calculate the duties and tariffs for cross border shipments. preferred_currency: allOf: - $ref: '#/components/schemas/currency' is_return: type: boolean description: Indicate if it's a return shipment calculate_rates_response_body: title: calculate_rates_response_body type: object description: A rate shipment response body required: - rate_response - shipment_id - ship_date - created_at - modified_at - shipment_status - return_to - confirmation - customs - advanced_options - insurance_provider - tags - packages - total_weight additionalProperties: false allOf: - $ref: '#/components/schemas/partial_shipment' - $ref: '#/components/schemas/rate_response' rate_response: title: rate_response type: object additionalProperties: false properties: rate_response: allOf: - $ref: '#/components/schemas/rates_information' description: The rates response rates_information: title: rates_information type: object description: A rates information resource additionalProperties: false properties: rates: type: array readOnly: true items: readOnly: true allOf: - $ref: '#/components/schemas/rate' description: Shipment Rates description: An array of shipment rates invalid_rates: type: array readOnly: true default: [] items: readOnly: true allOf: - $ref: '#/components/schemas/rate' description: Invalid Shipment Rate description: An array of invalid shipment rates rate_request_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the rate request shipment_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the shipment created_at: type: string format: date-time allOf: - $ref: '#/components/schemas/se_id' description: When the rate was created status: readOnly: true allOf: - $ref: '#/components/schemas/rate_response_status' errors: type: array items: allOf: - $ref: '#/components/schemas/error' rate: title: rate type: object description: A rate required: - rate_id - rate_type - carrier_id - shipping_amount - insurance_amount - confirmation_amount - other_amount - zone - package_type - guaranteed_service - negotiated_rate - service_type - service_code - trackable - carrier_code - carrier_nickname - carrier_friendly_name - validation_status - warning_messages - error_messages additionalProperties: false properties: rate_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the rate rate_type: readOnly: true allOf: - $ref: '#/components/schemas/rate_type' carrier_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the carrier shipping_amount: readOnly: true allOf: - $ref: '#/components/schemas/monetary_value' description: >- The shipping amount. Should be added with confirmation_amount, insurance_amount and other_amount to calculate the total purchase price. insurance_amount: readOnly: true allOf: - $ref: '#/components/schemas/monetary_value' description: >- The insurance amount. Should be added with shipping_amount, confirmation_amount and other_amount to calculate the total purchase price. confirmation_amount: readOnly: true allOf: - $ref: '#/components/schemas/monetary_value' description: >- The confirmation amount. Should be added with shipping_amount, insurance_amount and other_amount to calculate the total purchase price. other_amount: readOnly: true allOf: - $ref: '#/components/schemas/monetary_value' description: >- Any other charges associated with this rate. Should be added with shipping_amount, insurance_amount and confirmation_amount to calculate the total purchase price. requested_comparison_amount: readOnly: true allOf: - $ref: '#/components/schemas/monetary_value' description: The total shipping cost for the specified comparison_rate_type. tax_amount: readOnly: true allOf: - $ref: '#/components/schemas/monetary_value' description: >- Tariff and additional taxes associated with an international shipment. zone: type: integer format: int32 nullable: true readOnly: true minimum: 0 example: 6 description: > Certain carriers base [their rates](https://blog.stamps.com/2017/09/08/usps-postal-zones/) off of custom zones that vary depending upon the ship_to and ship_from location package_type: type: string nullable: true readOnly: true minLength: 1 example: package description: package type that this rate was estimated for delivery_days: type: integer format: int32 readOnly: true minimum: 1 example: 5 description: > The number of days estimated for delivery, this will show the _actual_ delivery time if for example, the package gets shipped on a Friday guaranteed_service: type: boolean readOnly: true description: Indicates if the rate is guaranteed. estimated_delivery_date: readOnly: true allOf: - $ref: '#/components/schemas/date' carrier_delivery_days: type: string readOnly: true minLength: 1 description: The carrier delivery days ship_date: type: string format: date-time readOnly: true minLength: 1 description: ship date negotiated_rate: type: boolean readOnly: true description: Indicates if the rates been negotiated service_type: type: string readOnly: true minLength: 1 description: service type service_code: type: string readOnly: true minLength: 1 description: service code for the rate trackable: type: boolean readOnly: true description: Indicates if rate is trackable carrier_code: type: string readOnly: true minLength: 1 description: carrier code carrier_nickname: type: string readOnly: true minLength: 1 description: carrier nickname carrier_friendly_name: type: string readOnly: true minLength: 1 description: carrier friendly name validation_status: readOnly: true allOf: - $ref: '#/components/schemas/validation_status' warning_messages: type: array readOnly: true minItems: 0 items: type: string readOnly: true minLength: 0 description: warning message description: The warning messages error_messages: type: array readOnly: true minItems: 0 items: type: string readOnly: true minLength: 0 description: error message description: The error messages rate_type: title: rate_type type: string enum: - check - shipment description: The possible rate type values validation_status: title: validation_status type: string enum: - valid - invalid - has_warnings - unknown description: The possible validation status values rate_response_status: title: rate_response_status type: string enum: - working - completed - partial - error description: The possible rate response status values compare_bulk_rates_request_body: title: compare_bulk_rates_request_body type: object description: A rate shipments request body required: - rate_options additionalProperties: false allOf: - $ref: '#/components/schemas/rate_request_rate_options' oneOf: - $ref: '#/components/schemas/rate_request_by_shipment_ids' - $ref: '#/components/schemas/rate_request_by_shipments' rate_request_rate_options: title: rate_request_rate_options type: object properties: rate_options: allOf: - $ref: '#/components/schemas/rate_request_body' description: The rate options rate_request_by_shipment_ids: title: rate_request_by_shipment_ids type: object required: - shipment_ids properties: shipment_ids: type: array items: allOf: - $ref: '#/components/schemas/se_id' description: shipment ids description: The array of shipment IDs rate_request_by_shipments: title: rate_request_by_shipments type: object required: - shipments properties: shipments: type: array minItems: 1 items: allOf: - $ref: '#/components/schemas/address_validating_shipment' description: The shipment to get a bulk rate estimate for description: The array of shipments to get bulk rate estimates for compare_bulk_rates_response_body: title: compare_bulk_rates_response_body type: array description: A bulk rate response body items: $ref: '#/components/schemas/bulk_rate' bulk_rate: title: bulk_rate type: object description: A bulk rate required: - rate_request_id - shipment_id - created_at - status - errors additionalProperties: false properties: rate_request_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the rate request shipment_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the shipment created_at: type: string format: date-time readOnly: true allOf: - $ref: '#/components/schemas/date_time' status: readOnly: true allOf: - $ref: '#/components/schemas/rate_response_status' errors: type: array readOnly: true items: readOnly: true allOf: - $ref: '#/components/schemas/error' description: An error that occurred while retrieving the bulk rate description: An array of errors that were returned while retrieving the bulk rate estimate_rates_request_body: title: estimate_rates_request_body type: object description: A rate estimate request body required: - from_country_code - from_postal_code - from_city_locality - from_state_province - to_country_code - to_postal_code - to_city_locality - to_state_province - weight - ship_date additionalProperties: false oneOf: - $ref: '#/components/schemas/rate_estimate_by_carrier_id' - $ref: '#/components/schemas/rate_estimate_by_carrier_ids' allOf: - $ref: '#/components/schemas/rate_estimate_options' rate_estimate_by_carrier_id: title: rate_estimate_by_carrier_id type: object properties: carrier_id: deprecated: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the carrier rate_estimate_by_carrier_ids: title: rate_estimate_by_carrier_ids type: object properties: carrier_ids: type: array minItems: 1 items: type: string allOf: - $ref: '#/components/schemas/se_id' description: carrier id description: Array of Carrier Ids rate_estimate_options: title: rate_estimate_options type: object properties: from_country_code: allOf: - $ref: '#/components/schemas/country_code' from_postal_code: allOf: - $ref: '#/components/schemas/postal_code' from_city_locality: type: string minLength: 1 example: Austin description: from postal code from_state_province: type: string minLength: 1 example: Austin description: From state province to_country_code: allOf: - $ref: '#/components/schemas/country_code' to_postal_code: allOf: - $ref: '#/components/schemas/postal_code' to_city_locality: type: string minLength: 1 example: Austin description: The city locality the package is being shipped to to_state_province: type: string minLength: 1 example: Houston description: To state province weight: allOf: - $ref: '#/components/schemas/weight' description: The weight of the package dimensions: allOf: - $ref: '#/components/schemas/dimensions' description: The dimensions of the package confirmation: allOf: - $ref: '#/components/schemas/delivery_confirmation' address_residential_indicator: allOf: - $ref: '#/components/schemas/address_residential_indicator' ship_date: type: string allOf: - $ref: '#/components/schemas/date_time' description: ship date estimate_rates_response_body: title: estimate_rates_response_body type: array description: A rate estimate response body items: allOf: - $ref: '#/components/schemas/rate_estimate' rate_estimate: title: rate_estimate type: object description: A rate estimate required: - rate_type - carrier_id - shipping_amount - insurance_amount - confirmation_amount - other_amount - zone - package_type - guaranteed_service - negotiated_rate - service_type - service_code - trackable - carrier_code - carrier_nickname - carrier_friendly_name - validation_status - warning_messages - error_messages additionalProperties: false properties: rate_type: readOnly: true allOf: - $ref: '#/components/schemas/rate_type' carrier_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the carrier shipping_amount: readOnly: true allOf: - $ref: '#/components/schemas/monetary_value' description: The shipping amount insurance_amount: readOnly: true allOf: - $ref: '#/components/schemas/monetary_value' description: The insurance amount confirmation_amount: readOnly: true allOf: - $ref: '#/components/schemas/monetary_value' description: The confirmation amount other_amount: readOnly: true allOf: - $ref: '#/components/schemas/monetary_value' description: Any other charges associated with this rate tax_amount: readOnly: true allOf: - $ref: '#/components/schemas/monetary_value' description: >- Tariff and additional taxes associated with an international shipment. zone: type: integer format: int32 nullable: true readOnly: true minimum: 0 example: 6 description: > Certain carriers base [their rates](https://blog.stamps.com/2017/09/08/usps-postal-zones/) off of custom zones that vary depending upon the ship_to and ship_from location package_type: type: string nullable: true readOnly: true minLength: 1 example: package description: package type that this rate was estimated for delivery_days: type: integer format: int32 readOnly: true minimum: 1 example: 5 description: > The number of days estimated for delivery, this will show the _actual_ delivery time if for example, the package gets shipped on a Friday guaranteed_service: type: boolean readOnly: true description: Indicates if the rate is guaranteed. estimated_delivery_date: readOnly: true allOf: - $ref: '#/components/schemas/date' carrier_delivery_days: type: string readOnly: true minLength: 1 description: The carrier delivery days ship_date: type: string format: date-time readOnly: true minLength: 1 description: ship date negotiated_rate: type: boolean readOnly: true description: Indicates if the rates been negotiated service_type: type: string readOnly: true minLength: 1 description: service type service_code: type: string readOnly: true minLength: 1 description: service code for the rate trackable: type: boolean readOnly: true description: Indicates if rate is trackable carrier_code: type: string readOnly: true minLength: 1 description: >- A [shipping carrier](https://www.shipengine.com/docs/carriers/setup/), such as `fedex`, `dhl_express`, `stamps_com`, etc. carrier_nickname: type: string readOnly: true minLength: 1 description: carrier nickname carrier_friendly_name: type: string readOnly: true minLength: 1 description: carrier friendly name validation_status: readOnly: true allOf: - $ref: '#/components/schemas/validation_status' warning_messages: type: array readOnly: true minItems: 0 items: type: string readOnly: true minLength: 0 description: warning message description: The warning messages error_messages: type: array readOnly: true minItems: 0 items: type: string readOnly: true minLength: 0 description: error message description: The error messages get_rate_by_id_response_body: title: get_rate_by_id_response_body type: object description: A rate response body required: - rates - invalid_rates - rate_request_id - shipment_id - created_at - status - errors additionalProperties: false allOf: - $ref: '#/components/schemas/rate' get_service_points_request: title: get_service_points_request oneOf: - $ref: '#/components/schemas/get_service_points_request_body' get_service_points_request_body: title: get_service_points_request_body type: object description: >- A get service points request body. Caller must provide exactly one of address_query, address, or lat / long pair. required: - providers properties: address_query: type: string description: Unstructured text to search for service points by. example: 177A Bleecker Street New York address: type: object description: Structured address to search by. required: - country_code properties: address_line1: type: string example: 1999 Bishop Grandin Blvd. description: >- The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines. address_line2: type: string address_line3: type: string city_locality: type: string description: The name of the city or locality state_province: type: string description: >- The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation. postal_code: type: string allOf: - $ref: '#/components/schemas/postal_code' country_code: type: string allOf: - $ref: '#/components/schemas/country_code' providers: type: array description: An array of shipping service providers and service codes items: type: object properties: carrier_id: type: string example: se-123456 description: Uniquely identifies a carrier connection service_code: type: array items: type: string example: chronoclassic description: Uniquely identifies a shipping service lat: format: double type: number example: 48.874518928233094 description: >- The latitude of the point. Represented as signed degrees. Required if long is provided. http://www.geomidpoint.com/latlon.html long: format: double type: number example: 2.3591775711639404 description: >- The longitude of the point. Represented as signed degrees. Required if lat is provided. http://www.geomidpoint.com/latlon.html radius: format: int32 type: integer example: 500 description: Search radius in kilometers max_results: format: int32 type: integer example: 25 description: The maximum number of service points to return list_service_points_response_body: title: list_service_points_response_body type: object description: A list service points response body properties: lat: format: double type: number example: 48.842608 description: >- The latitude of the point. Represented as signed degrees. Required if long is provided. http://www.geomidpoint.com/latlon.html long: format: double type: number example: 0.032875 description: >- The longitude of the point. Represented as signed degrees. Required if lat is provided. http://www.geomidpoint.com/latlon.html service_points: type: array items: type: object properties: carrier_code: allOf: - $ref: '#/components/schemas/carrier_code' service_codes: type: array items: type: string example: chronoclassic description: >- A [shipping carrier](https://www.shipengine.com/docs/carriers/setup/) service code. service_point_id: type: string example: '614940' description: A unique identifier for a carrier drop off point. company_name: type: string example: My fancy company name description: >- If this is a business address, then the company name should be specified here. address_line1: type: string example: PLACE DU CANADA description: >- The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines. city_locality: type: string example: TRUN description: The name of the city or locality state_province: type: string example: TRUN description: >- The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation. postal_code: allOf: - $ref: '#/components/schemas/postal_code' country_code: allOf: - $ref: '#/components/schemas/country_code' phone_number: type: string example: 555-555-5555 description: Phone number associated lat: format: double type: number example: 48.842608 description: >- The latitude of the point. Represented as signed degrees. Required if long is provided. http://www.geomidpoint.com/latlon.html long: format: double type: number example: 0.032875 description: >- The longitude of the point. Represented as signed degrees. Required if lat is provided. http://www.geomidpoint.com/latlon.html distance_in_meters: format: double type: number example: 728.9959308847579 description: Distance in meters hours_of_operation: type: object description: Hours of operation properties: monday: type: array items: type: object properties: open: type: string example: '09:15' description: Opening time close: type: string example: '12:00' description: Closing time tuesday: type: array items: type: object properties: open: type: string example: '09:15' description: Opening time close: type: string example: '12:00' description: Closing time wednesday: type: array items: type: object properties: open: type: string example: '09:15' description: Opening time close: type: string example: '12:00' description: Closing time thursday: type: array items: type: object properties: open: type: string example: '09:15' description: Opening time close: type: string example: '12:00' description: Closing time friday: type: array items: type: object properties: open: type: string example: '09:15' description: Opening time close: type: string example: '12:00' description: Closing time saturday: type: array items: type: object properties: open: type: string example: '09:15' description: Opening time close: type: string example: '12:00' description: Closing time sunday: type: array items: type: object properties: open: type: string example: '09:15' description: Opening time close: type: string example: '12:00' description: Closing time features: type: array description: Service features items: type: string enum: - drop_off_point - pickup_point - print_services - after_hours_locker - after_hours_dropbox type: type: string description: Service point type default: pudo enum: - pudo - locker errors: type: array readOnly: true items: allOf: - $ref: '#/components/schemas/error' description: The errors associated with the failed API call get_service_point_by_id_response_body: title: get_service_point_by_id_response_body type: object description: A get service point by ID response body properties: service_point: type: object properties: carrier_code: allOf: - $ref: '#/components/schemas/carrier_code' service_codes: type: array items: type: string description: >- A [shipping carrier](https://www.shipengine.com/docs/carriers/setup/) service code. service_point_id: type: string example: '614940' description: A unique identifier for a carrier drop off point. company_name: type: string example: My fancy company name description: >- If this is a business address, then the company name should be specified here. address_line1: type: string example: PLACE DU CANADA description: >- The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines. city_locality: type: string example: TRUN description: The name of the city or locality state_province: type: string example: TRUN description: >- The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation. postal_code: allOf: - $ref: '#/components/schemas/postal_code' country_code: allOf: - $ref: '#/components/schemas/country_code' phone_number: type: string example: 555-555-5555 description: Phone number associated lat: format: double type: number example: 48.842608 description: >- The latitude of the point. Represented as signed degrees. Required if long is provided. http://www.geomidpoint.com/latlon.html long: format: double type: number example: 0.032875 description: >- The longitude of the point. Represented as signed degrees. Required if lat is provided. http://www.geomidpoint.com/latlon.html hours_of_operation: type: object description: Hours of operation properties: monday: type: array items: type: object properties: open: type: string example: '09:15' description: Opening time close: type: string example: '12:00' description: Closing time tuesday: type: array items: type: object properties: open: type: string example: '09:15' description: Opening time close: type: string example: '12:00' description: Closing time wednesday: type: array items: type: object properties: open: type: string example: '09:15' description: Opening time close: type: string example: '12:00' description: Closing time thursday: type: array items: type: object properties: open: type: string example: '09:15' description: Opening time close: type: string example: '12:00' description: Closing time friday: type: array items: type: object properties: open: type: string example: '09:15' description: Opening time close: type: string example: '12:00' description: Closing time saturday: type: array items: type: object properties: open: type: string example: '09:15' description: Opening time close: type: string example: '12:00' description: Closing time sunday: type: array items: type: object properties: open: type: string example: '09:15' description: Opening time close: type: string example: '12:00' description: Closing time features: type: array description: Service features items: type: string enum: - drop_off_point - pickup_point - print_services - after_hours_locker - after_hours_dropbox type: type: string description: Service point type default: pudo enum: - pudo - locker shipments_sort_by: title: shipments_sort_by type: string enum: - modified_at - created_at description: The possible shipments sort by values list_shipments_response_body: title: list_shipments_response_body type: object description: A list shipment response body required: - shipments - total - page - pages - links additionalProperties: false properties: shipments: type: array readOnly: true items: readOnly: true allOf: - $ref: '#/components/schemas/shipment' description: A shipment object description: The list of shipments returned by the api call total: type: integer format: int64 readOnly: true minimum: 0 example: 1990 description: Total number of shipments returned by the api call page: type: integer format: int32 readOnly: true minimum: 1 example: '????' pages: type: integer format: int32 readOnly: true minimum: 1 links: readOnly: true allOf: - $ref: '#/components/schemas/pagination_link' create_shipments_request_body: title: create_shipments_request_body type: object description: A create shipments request body required: - shipments additionalProperties: false properties: shipments: type: array minItems: 1 items: allOf: - $ref: '#/components/schemas/address_validating_shipment' description: An array of shipments to be created. create_shipments_response_body: title: create_shipments_response_body type: object description: A create shipments response body required: - has_errors - shipments additionalProperties: false properties: has_errors: type: boolean default: false description: Indicates if errors occured while creating the shipments shipments: type: array items: allOf: - $ref: '#/components/schemas/create_and_validate_shipment' description: The shipment that was created. description: An array of shipments that were created. create_and_validate_shipment: title: create_and_validate_shipment type: object description: A create and validate shipment resource additionalProperties: false allOf: - $ref: '#/components/schemas/partial_shipment' - $ref: '#/components/schemas/create_shipment_response_body_fields' create_shipment_response_body_fields: title: create_shipment_response_body_fields type: object properties: errors: type: array deprecated: true items: type: string minLength: 1 example: Parameter value '100000000.00' is out of range. description: An error that occurred while creating a shipment. description: An array of errors that occurred while creating shipment. readOnly: true address_validation: allOf: - $ref: '#/components/schemas/address_validation_result' description: The address validation get_shipment_by_external_id_response_body: title: get_shipment_by_external_id_response_body type: object description: A get shipment by external id response body additionalProperties: false allOf: - $ref: '#/components/schemas/shipment' parse_shipment_request_body: title: parse_shipment_request_body type: object description: > The only required field is `text`, which is the text to be parsed. You can optionally also provide a `shipment` containing any already-known values. For example, you probably already know the `ship_from` address, and you may also already know what carrier and service you want to use. required: - text additionalProperties: false properties: text: type: string minLength: 1 example: > I have a 4oz package that's 5x10x14in, and I need to ship it to Margie McMiller at 3800 North Lamar suite 200 in austin, tx 78652. Please send it via USPS first class and require an adult signature. It also needs to be insured for $400. description: The unstructured text that contains shipping-related entities shipment: allOf: - $ref: '#/components/schemas/partial_shipment' description: > You can optionally provide a `shipment` object containing any already-known values. For example, you probably already know the `ship_from` address, and you may also already know what carrier and service you want to use. parse_shipment_response_body: title: parse_shipment_response_body type: object description: > The parsed shipment, as well as a confidence score and a list of all the shipping entities that were recognized in the text. required: - score - shipment - entities additionalProperties: false properties: score: type: number format: double minimum: 0 maximum: 1 description: > A confidence score between zero and one that indicates how certain the API is that it understood the text. shipment: allOf: - $ref: '#/components/schemas/partial_shipment' description: > The parsed shipment. This shipment may not be complete, depending on how much information was included in the text and how confident the API is about each recognized entity. > **Note:** The shipment-recognition API does not currently perform any validation of the parsed addresses, so we recommend that you use the [address-validation API](https://www.shipengine.com/docs/addresses/validation/) to ensure that the addresses are correct. entities: type: array minItems: 0 items: $ref: '#/components/schemas/recognized_entity' description: > All of the entities that were recognized in the text. An "entity" is a single piece of data, such as a city, a postal code, a carrier name, or a package weight. Each entity includes the original text and the parsed value. get_shipment_by_id_response_body: title: get_shipment_by_id_response_body type: object description: A get shipment by id response body additionalProperties: false allOf: - $ref: '#/components/schemas/shipment' update_shipment_request_body: title: update_shipment_request_body type: object description: An update shipment request body required: - ship_to - ship_from additionalProperties: false allOf: - $ref: '#/components/schemas/partial_shipment' - $ref: '#/components/schemas/update_shipment_fields' update_shipment_fields: title: update_shipment_fields type: object properties: validate_address: default: no_validation allOf: - $ref: '#/components/schemas/validate_address' update_shipment_response_body: title: update_shipment_response_body type: object description: An update shipment response body required: - errors - has_errors - address_validation - shipment_id - carrier_id - service_code - ship_date - created_at - shipment_status - ship_to - ship_from - return_to - confirmation - customs - advanced_options - insurance_provider - tags - packages - total_weight additionalProperties: false allOf: - $ref: '#/components/schemas/create_and_validate_shipment' list_shipment_rates_response_body: title: list_shipment_rates_response_body type: object description: A list shipment rates response body required: - rates - invalid_rates - rate_request_id - shipment_id - created_at - status - errors additionalProperties: false allOf: - $ref: '#/components/schemas/rates_information' update_shipments_tags_request_body: title: update_shipments_tags_request_body type: object description: A request body with shipments and tags allOf: - $ref: '#/components/schemas/update_shipments_tags' update_shipments_tags: title: update_shipments_tags type: object properties: shipments_tags: type: array items: type: object properties: shipment_id: type: string tags: type: array items: type: string example: shipments_tags: - shipment_id: se-1014296 tags: - Fragile - International - shipment_id: se-1014297 tags: - Fragile - International tag_shipment_response_body: title: tag_shipment_response_body type: object description: Get shipment tags response body required: - tags additionalProperties: false properties: tags: type: array items: type: string tag_name: title: tag_name type: string minLength: 1 example: Fragile description: > Tags are arbitrary strings that you can use to categorize shipments. For example, you may want to use tags to distinguish between domestic and international shipments, or between insured and uninsured shipments. Or maybe you want to create a tag for each of your customers so you can easily retrieve every shipment for a customer. list_tags_response_body: title: list_tags_response_body type: object description: Response body from a successful GET /tags API call additionalProperties: false properties: tags: type: array items: allOf: - $ref: '#/components/schemas/tag' description: The array of tags returned by the API call create_tag_response_body: title: create_tag_response_body type: object description: Response body for creating tags additionalProperties: false allOf: - $ref: '#/components/schemas/tag' redirect: title: redirect type: string enum: - shipengine-dashboard description: The resource to return a redirect URL to. tokens_get_ephemeral_token_response_body.yaml: title: tokens_get_ephemeral_token_response_body.yaml type: object properties: token: type: string description: The requested token that expires in 10 seconds. redirect_url: type: string description: The redirect url formatted with the requested token. get_tracking_log_response_body: title: get_tracking_log_response_body type: object description: A get tracking log response body required: - tracking_number - tracking_url - status_code - carrier_code - carrier_id - carrier_detail_code - carrier_status_code - estimated_delivery_date - events additionalProperties: false allOf: - $ref: '#/components/schemas/tracking_information' list_warehouses_response_body: title: list_warehouses_response_body type: object description: A warehouse list response body required: - warehouses additionalProperties: false properties: warehouses: type: array readOnly: true items: readOnly: true allOf: - $ref: '#/components/schemas/warehouse' description: The array of warehouses returned by the API call warehouse: title: warehouse type: object description: A warehouse additionalProperties: false properties: warehouse_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the warehouse is_default: nullable: true type: boolean default: false description: Designates which single warehouse is the default on the account name: type: string minLength: 1 example: Zero Cool HQ description: Name of the warehouse created_at: type: string format: date-time readOnly: true example: '2019-06-25T18:12:35.583Z' minLength: 1 description: Timestamp that indicates when the warehouse was created origin_address: allOf: - $ref: '#/components/schemas/address' description: The origin address of the warehouse return_address: allOf: - $ref: '#/components/schemas/address' description: The return address associated with the warehouse create_warehouse_request_body: title: create_warehouse_request_body type: object description: A create warehouse request body required: - name - origin_address additionalProperties: false allOf: - $ref: '#/components/schemas/warehouse' create_warehouse_response_body: title: create_warehouse_response_body type: object description: A create warehouse response body required: - warehouse_id - name - created_at - origin_address - return_address additionalProperties: false allOf: - $ref: '#/components/schemas/warehouse' get_warehouse_by_id_response_body: title: get_warehouse_by_id_response_body type: object description: A get warehouse by id response body required: - warehouse_id - name - created_at - origin_address - return_address additionalProperties: false allOf: - $ref: '#/components/schemas/warehouse' update_warehouse_request_body: title: update_warehouse_request_body type: object description: An update warehouse request body required: - name - origin_address additionalProperties: false allOf: - $ref: '#/components/schemas/warehouse' update_warehouse_settings_request_body: title: update_warehouse_settings_request_body type: object description: An update warehouse settings request body properties: is_default: type: boolean nullable: true description: The default property on the warehouse. example: true additionalProperties: false responses: 400_error_response: description: The request contained errors. content: application/json: schema: $ref: '#/components/schemas/error_response_body' 404_error_response: description: The specified resource does not exist. content: application/json: schema: $ref: '#/components/schemas/error_response_body' 500_error_response: description: | An error occurred on ShipEngine's side. > This error will automatically be reported to our engineers. content: application/json: schema: $ref: '#/components/schemas/error_response_body' 409_error_response: description: The request conflicts with an existing resource. content: application/json: schema: $ref: '#/components/schemas/error_response_body' securitySchemes: api_key: type: apiKey name: API-Key in: header description: > To authenticate yourself to ShipEngine, you need to include an `API-Key` header in each API call. If you don't include a key when making an API request, or if you use an incorrect or expired key, then ShipEngine will respond with a `401 Unauthorized` error. Learn more about API keys in our [authentication guide](https://www.shipengine.com/docs/auth/). tags: - name: account description: | For additional information about the ShipEngine account. x-displayName: Account - name: addresses description: > No matter your shipping volume, failed deliveries and address change surcharges cut into your bottom line and damage perception with customers. Our address validation services ensure your packages make it to the right place the first time. [Learn how to leverage our address validation services here.](https://www.shipengine.com/docs/addresses/validation/) ShipEngine supports address validation for virtually every country on Earth, including the United States, Canada, Great Britain, Australia, Germany, France, Norway, Spain, Sweden, Israel, Italy, and over 160 others. externalDocs: url: 'https://www.shipengine.com/docs/addresses/validation/' description: > Address validation ensures accurate addresses and can lead to reduced shipping costs by preventing address correction surcharges. ShipEngine cross references multiple databases to validate addresses and identify potential deliverability issues. x-displayName: Addresses - name: batches description: | batches x-displayName: Batches - name: carrier_accounts description: | carrier accounts x-displayName: Carrier Accounts - name: carriers description: | carriers x-displayName: Carriers - name: downloads description: | downloads x-displayName: Downloads - name: insurance description: | insurance x-displayName: Insurance - name: labels description: > Print shipping labels for any of the top global carriers in minutes—instead of weeks. Simply [connect your existing carrier accounts](https://www.shipengine.com/docs/carriers/setup/) in the API dashboard, and then [begin creating labels](https://www.shipengine.com/docs/shipping/use-a-carrier-service/). externalDocs: url: 'https://www.shipengine.com/docs/labels/create-a-label/' description: >- Follow this quick start guide to create your first shipping label with ShipEngine x-displayName: Labels - name: manifests description: | manifests x-displayName: Manifests - name: package_pickups description: Scheduled package pickups x-displayName: Package Pickups - name: package_types description: | custom package types x-displayName: Package Types - name: rates description: > Make sure you ship as cost-effectively as possible by [quickly comparing rates](https://www.shipengine.com/docs/rates/) using the ShipEngine Rates API. As long as you have the carrier connected to your account, you'll be able to see and compare different rates and services. externalDocs: url: 'https://www.shipengine.com/docs/rates/' description: > This quick start guide shows you how to get shipping rates for multiple carriers so you can choose the fastest, cheapest, or most reliable option. x-displayName: Rates - name: service_points x-displayName: Service Points - name: shipments description: > Shipments are at the center of the ShipEngine API. A shipment is the first step in [creating a shipping label](https://www.shipengine.com/docs/labels/create-a-label/), or [creating a manifest](https://www.shipengine.com/docs/shipping/manifests/). It's also essential for [getting shipping rates](https://www.shipengine.com/docs/rates/). externalDocs: url: 'https://www.shipengine.com/docs/shipping/create-a-shipment/' description: > Learn about the shipment object model concept, and how to persist and re-use shipment data inside ShipEngine. x-displayName: Shipments - name: tags description: | tags x-displayName: Tags - name: tokens x-displayName: Tokens - name: tracking description: > [Track packages](https://www.shipengine.com/docs/tracking/) across any of our 20+ supported carrier accounts and create tracking events to keep your customers up-to-date. Easily integrate real-time tracking information for shipments into your app, email, or SMS. externalDocs: url: 'https://www.shipengine.com/docs/tracking/' description: >- Learn how to use ShipEngine to track any package with a carrier and a tracking number x-displayName: Tracking - name: warehouses description: | warehouses x-displayName: Warehouses - name: webhooks description: > [Webhooks](https://www.shipengine.com/docs/tracking/webhooks/) are a powerful feature of ShipEngine that can save you from sending repeated polling requests to check on the state of something. With webhooks, ShipEngine will automatically contact your servers when the stage changes. This can include [parcel tracking](https://www.shipengine.com/docs/tracking/) events, notification of the completion of a [batch operation](https://www.shipengine.com/docs/labels/bulk/), or new [salses orders](https://www.shipengine.com/docs/orders/). externalDocs: url: 'https://www.shipengine.com/docs/tracking/webhooks/' description: Learn how to setup webhooks and start listening to ShipEngine events. x-displayName: Webhooks security: - api_key: [] externalDocs: url: 'https://www.shipengine.com/docs/' description: > ShipEngine's documentation is designed to help you start shipping as quickly as possible. With easy-to-follow tutorials, detailed reference docs, and ready-made recipes for common use cases, you'll see real results in no time at all.