openapi: 3.1.0 info: title: ShipStation API v2 version: 2.0.0 license: name: MIT url: https://opensource.org/license/mit/ servers: - url: https://api.shipstation.com description: Production security: - api_keys: [] paths: /v2/inventory: x-visibility: public summary: Inventory description: | Manage inventory, adjust quantities, and handle warehouses and locations. get: operationId: getInventoryLevels summary: List SKU inventory levels tags: - inventory parameters: - name: sku description: Optional list of SKUs to filter down to in: query schema: type: string - name: inventory_warehouse_id in: query schema: type: string - name: inventory_location_id in: query schema: type: string - name: group_by in: query description: Get counts for SKUs across locations or warehouses schema: type: string enum: - warehouse - location - name: page_size in: query schema: type: integer responses: '200': description: Inventory levels for SKUs content: application/json: schema: type: object properties: inventory: type: array items: type: object properties: sku: type: string on_hand: type: integer allocated: type: integer available: type: integer average_cost: type: object properties: amount: type: number currency: type: string inventory_warehouse_id: type: string inventory_location_id: type: string total: type: integer page: type: integer pages: type: integer links: type: object properties: first: type: object properties: href: type: string last: type: object properties: href: type: string prev: type: object properties: href: type: string next: type: object properties: href: type: string post: operationId: updateSKUStockLevels summary: Update SKU stock levels and related properties tags: - inventory requestBody: required: true content: application/json: schema: type: object required: - transaction_type - sku - quantity - inventory_location_id properties: transaction_type: description: | The type of update to perform: increment: Increase inventory quantity for specified location. decrement: Decreate inventory quantity for specified location given a set of filters. adjust: Adjust on hand quantity of inventory for specified location to the quantity indicated. This is done by either adding or removing inventory in the condition specified. modify: Modify attributes on specified inventory. The filters work the same as for decrement transaction type. type: string enum: - increment - decrement - adjust - modify inventory_location_id: type: string sku: type: string quantity: type: integer cost: type: object properties: amount: type: number currency: type: string condition: type: string enum: - sellable - damaged - expired - qa_hold lot: type: string usable_start_date: type: string format: date-time usable_end_date: type: string format: date-time effective_at: type: string format: date-time reason: type: string notes: type: string new_inventory_location_id: description: >- Used with the modify transaction type to move inventory to a new location type: string new_cost: type: object description: >- Used with the modify transaction type to update the cost of existing inventory properties: amount: type: number currency: type: string new_condition: description: >- Used with the modify transaction type to change the condition of existing inventory type: string enum: - sellable - damaged - expired - qa_hold responses: '204': description: Inventory successfully updated /v2/inventory_warehouses: get: operationId: getInventoryWarehouses summary: List all inventory warehouses tags: - inventory parameters: - name: page_size in: query schema: type: integer responses: '200': description: List of inventory warehouses content: application/json: schema: type: object properties: inventory_warehouses: type: array items: type: object properties: inventory_warehouse_id: type: string name: type: string created_at: type: string format: date-time updated_at: type: string format: date-time total: type: integer page: type: integer pages: type: integer links: type: object properties: first: type: object properties: href: type: string last: type: object properties: href: type: string prev: type: object properties: href: type: string next: type: object properties: href: type: string post: operationId: addNewInventoryWarehouse summary: Create a new inventory warehouse tags: - inventory requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string responses: '200': description: Inventory warehouse successfully created content: application/json: schema: type: object properties: inventory_warehouse_id: type: string name: type: string created_at: type: string format: date-time updated_at: type: string format: date-time /v2/inventory_warehouses/{inventory_warehouse_id}: get: operationId: getInventoryWarehouseById summary: >- Get a specific inventory warehouse and related properties using its warehouse ID tags: - inventory parameters: - name: inventory_warehouse_id in: path required: true schema: type: string responses: '200': description: Inventory warehouse details content: application/json: schema: type: object properties: inventory_warehouse_id: type: string name: type: string created_at: type: string format: date-time updated_at: type: string format: date-time put: operationId: updateInventoryWarehouse summary: Update an inventory warehouse name tags: - inventory parameters: - name: inventory_warehouse_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: name: type: string responses: '204': description: Inventory warehouse successfully updated delete: operationId: deleteInventoryWarehouse summary: Delete an inventory warehouse tags: - inventory parameters: - name: inventory_warehouse_id in: path required: true schema: type: string - name: remove_inventory in: query required: false description: > If 1, remove all inventory from the warehouse before deleting it. If 0 or missing and the warehouse has On Hand inventory, the request will fail. schema: type: string enum: - '0' - '1' responses: '204': description: Inventory warehouse successfully deleted /v2/inventory_locations: get: operationId: listInventoryLocations summary: List all inventory locations tags: - inventory parameters: - name: page_size in: query schema: type: integer responses: '200': description: List of inventory locations content: application/json: schema: type: object properties: inventory_locations: type: array items: type: object properties: inventory_location_id: type: string name: type: string inventory_warehouse_id: type: string created_at: type: string format: date-time updated_at: type: string format: date-time total: type: integer page: type: integer pages: type: integer links: type: object properties: first: type: object properties: href: type: string last: type: object properties: href: type: string prev: type: object properties: href: type: string next: type: object properties: href: type: string post: operationId: createInventoryLocation summary: Create a new inventory location tags: - inventory requestBody: required: true content: application/json: schema: type: object required: - name - inventory_warehouse_id properties: name: type: string inventory_warehouse_id: type: string responses: '200': description: Inventory location successfully created content: application/json: schema: type: object properties: inventory_location_id: type: string name: type: string inventory_warehouse_id: type: string created_at: type: string format: date-time updated_at: type: string format: date-time /v2/inventory_locations/{inventory_location_id}: get: operationId: getInventoryLocationById summary: Get inventory location by ID tags: - inventory parameters: - name: inventory_location_id in: path required: true schema: type: string responses: '200': description: Inventory location details content: application/json: schema: type: object properties: inventory_location_id: type: string name: type: string inventory_warehouse_id: type: string created_at: type: string format: date-time updated_at: type: string format: date-time put: operationId: updateInventoryLocation summary: Update an inventory location name tags: - inventory parameters: - name: inventory_location_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: name: type: string responses: '204': description: Inventory location successfully updated delete: operationId: deleteInventoryLocationById summary: Delete an inventory location tags: - inventory parameters: - name: inventory_location_id in: path required: true schema: type: string - name: remove_inventory in: query description: > If 1, remove all inventory from the location before deleting it. If 0 or missing and the location has On Hand inventory, the request will fail. schema: type: string enum: - '0' - '1' responses: '204': description: Inventory location successfully deleted /v2/batches: x-visibility: public summary: Batches description: > Batches are an advanced feature designed for those who need to generate hundreds or thousands of labels at a time. When ShipStation generates labels it relies on many carriers dependencies and variables to fulfill your requests, which can take a few minutes. Using batches reduces this time significantly for those with high label volume. get: summary: List batches description: List the batches associated with your ShipStation account. operationId: list_batches tags: - batches parameters: - $ref: '#/components/parameters/batch_status_query_param' - $ref: '#/components/parameters/page_query_param' - $ref: '#/components/parameters/page_size_query_param' - $ref: '#/components/parameters/sort_dir_query_param' - $ref: '#/components/parameters/batch_number_query_param' - 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/ListBatchesResponseBody' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' post: summary: Create a batch description: Create a batch containing multiple labels. tags: - batches operationId: create_batch requestBody: required: true content: application/json: schema: title: create_batch_request oneOf: - $ref: '#/components/schemas/create_batch_request_body' - $ref: '#/components/schemas/create_and_process_batch_request_body' responses: '200': description: The requested object creation was a success. content: application/json: schema: $ref: '#/components/schemas/CreateBatchResponseBody' '207': description: >- The request was a partial success. It contains results, as well as processing errors. content: application/json: schema: $ref: '#/components/schemas/CreateBatchResponseBody' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/ServerError' /v2/batches/external_batch_id/{external_batch_id}: x-visibility: public summary: External batch id description: An external batch identifier parameters: - $ref: '#/components/parameters/external_batch_id_path_param' get: summary: Get batch by external id description: Retreive a batch using an external batch 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/BadRequest' '404': description: >- The API returns a 404 response when no `batch` corresponds to the `external_batch_id` provided. content: application/json: schema: $ref: '#/components/schemas/error_response_body' '500': $ref: '#/components/responses/ServerError' /v2/batches/{batch_id}: x-visibility: public summary: Batch by id description: Check the status of your batch by retrieving it with a batch id. parameters: - $ref: '#/components/parameters/batch_id_path_param' delete: summary: Delete batch by id description: Delete a batch based on its batch id. Sets its status to 'archived'. operationId: delete_batch tags: - batches responses: '204': $ref: '#/components/responses/NoContent' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' get: summary: Get batch by id description: Get batch details for a specific batch 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/BadRequest' '404': description: >- The API returns a 404 response when no `batch` corresponds to the `batch_id` provided. content: application/json: schema: title: empty_response_body type: string minLength: 0 maxLength: 0 '500': $ref: '#/components/responses/ServerError' put: summary: Update batch status to 'archived' by id description: Update a batch by id setting its status to 'archived'. operationId: update_batch tags: - batches responses: '204': $ref: '#/components/responses/NoContent' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/batches/{batch_id}/add: x-visibility: public summary: Add shipment ids or rate ids to a batch. description: > You can continue to add `shipment_ids`` and/or `rate_ids`` to already created batches until you are ready to process the batch. parameters: - $ref: '#/components/parameters/batch_id_path_param' 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/create_and_process_batch_request_body' responses: '204': $ref: '#/components/responses/NoContent' '400': $ref: '#/components/responses/BadRequest' '404': description: >- The API returns a 404 response when no `batch` corresponds to the `batch_id` provided. content: application/json: schema: title: empty_response_body type: string minLength: 0 maxLength: 0 '500': $ref: '#/components/responses/ServerError' /v2/batches/{batch_id}/errors: x-visibility: public summary: Batch errors description: > Errors in batches must be handled differently from synchronous requests. You must retrieve the status of your batch by getting a batch and getting an overview of the statuses or by listing the batch errors. parameters: - $ref: '#/components/parameters/batch_id_path_param' get: summary: Get batch errors description: > Errors in batches must be handled differently from synchronous requests. You must retrieve the status of your batch by getting a batch and getting an overview of the statuses or by listing the batch errors. tags: - batches operationId: list_batch_errors parameters: - $ref: '#/components/parameters/page_query_param' - $ref: '#/components/parameters/pagesize_query_param' responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/list_batch_errors_response_body' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/batches/{batch_id}/process/labels: x-visibility: public summary: Process Batch ID Labels description: Process Batch ID Labels parameters: - $ref: '#/components/parameters/batch_id_path_param' post: summary: Process batch id labels description: Create and purchase the labels for the shipments included in the batch. tags: - batches operationId: process_batch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/process_batch_request_body' responses: '204': $ref: '#/components/responses/NoContent' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/batches/{batch_id}/remove: x-visibility: public summary: Remove batch by id description: Remove specific shipment ids or rate ids from a batch. parameters: - $ref: '#/components/parameters/batch_id_path_param' post: summary: Remove from batch description: Remove specific shipment ids or rate ids 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': $ref: '#/components/responses/NoContent' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/carriers: x-visibility: public summary: Carriers description: > Carriers specializes in transporting freight from one destination to another. ShipStation allows you to easily integrate with multiple carriers so you can choose the shipping services that are 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: title: get_carriers_response_body allOf: - $ref: '#/components/schemas/list_carriers_response_body' - $ref: '#/components/schemas/error_response_body' '207': description: >- The request was a partial success. It contains results, as well as errors. content: application/json: schema: title: get_carriers_response_body allOf: - $ref: '#/components/schemas/list_carriers_response_body' - $ref: '#/components/schemas/error_response_body' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/carriers/{carrier_id}: x-visibility: public summary: Individual carriers description: >- Perform actions and get information on individual carriers connected to your account. parameters: - $ref: '#/components/parameters/carrier_id_path_param' get: summary: Get carrier by id description: Retrive details about a specific carrier by its carrier 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/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/carriers/{carrier_id}/options: x-visibility: public summary: Carrier options description: >- Carriers support various options for the shipments they transport. For example, non-machinable, is_alcohol, fragile, etc. parameters: - $ref: '#/components/parameters/carrier_id_path_param' get: summary: Get carrier options description: Get a list of the options available for a specific carriers. 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/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/carriers/{carrier_id}/packages: x-visibility: public summary: Carrier packages description: > Carriers support many different package types. ShipStation supports retrieving all available package types so you can best determine what is right for your particular shipments. parameters: - $ref: '#/components/parameters/carrier_id_path_param' get: summary: List carrier package types description: List the package types associated with a specific 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/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/carriers/{carrier_id}/services: x-visibility: public summary: Carrier services description: > Carrier services usually refer to the various shipping classes a carrier makes available to its customers. For example, Priority mail, overnight, international, etc. parameters: - $ref: '#/components/parameters/carrier_id_path_param' get: summary: List carrier services description: List the services associated with a specific 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/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/downloads/{dir}/{subdir}/{filename}: x-visibility: public 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: - $ref: '#/components/parameters/subdir_path_param' - $ref: '#/components/parameters/filename_path_param' - $ref: '#/components/parameters/dir_path_param' get: summary: Download file description: Download labels and other shipment-related documents. 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: title: download_file_pdf_response_body type: string format: binary image/png: schema: title: download_file_png_response_body type: string format: binary application/zpl: schema: title: download_file_zpl_response_body type: string format: binary '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/fulfillments: x-visibility: public summary: Fulfillments description: > Fulfillments represent completed shipments that have been marked as shipped with tracking information. Use fulfillments to notify customers and marketplaces when orders have been shipped and to provide tracking details. get: summary: List fulfillments description: > Retrieve a list of fulfillments based on various filter criteria. You can filter by shipment details, tracking information, dates, and more to find the specific fulfillments you need. tags: - fulfillments operationId: list_fulfillments parameters: - name: ship_to_name in: query required: false schema: type: string description: Filter by recipient name - name: ship_to_country_code in: query required: false schema: type: string description: Filter by ship-to country code (2-letter ISO country code) example: US - name: shipment_number in: query required: false schema: type: string description: Filter by shipment number (order number) - name: shipment_id in: query required: false schema: type: string description: Filter by specific shipment id example: se-12345678 - name: fulfillment_id in: query required: false schema: type: string description: Filter by specific fulfillment id example: se-12345678 - name: batch_id in: query required: false schema: type: string description: Filter by batch id example: se-12345678 - name: order_source_id in: query required: false schema: type: string description: Filter by order source id (store id) example: se-12345678 - name: fulfillment_provider_code in: query required: false schema: type: string description: Filter by fulfillment provider code - name: tracking_number in: query required: false schema: type: string description: Filter by tracking number - name: ship_date_start in: query required: false schema: type: string format: date-time description: Filter by ship date start (inclusive) example: '2024-01-01T00:00:00Z' - name: ship_date_end in: query required: false schema: type: string format: date-time description: Filter by ship date end (inclusive) example: '2024-01-31T23:59:59Z' - name: create_date_start in: query required: false schema: type: string format: date-time description: Filter by creation date start (inclusive) example: '2024-01-01T00:00:00Z' - name: create_date_end in: query required: false schema: type: string format: date-time description: Filter by creation date end (inclusive) example: '2024-01-31T23:59:59Z' - name: page in: query required: false schema: type: integer minimum: 1 default: 1 description: Page number for pagination - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 500 default: 25 description: Number of results per page - name: sort_dir in: query required: false schema: type: string enum: - asc - desc default: asc description: Sort direction - name: sort_by in: query required: false schema: type: string enum: - created_at - modified_at - shipped_at default: created_at description: Sort field responses: '200': description: The request was a success. content: application/json: schema: type: object properties: fulfillments: type: array items: $ref: '#/components/schemas/fulfillment' page: type: integer description: Current page number example: 1 pages: type: integer description: Total number of pages example: 10 total: type: integer example: 100 description: Total number of fulfillments links: type: object properties: first: type: object properties: href: type: string example: >- https://api.shipstation.com/v2/fulfillments?page=1&page_size=100 last: type: object properties: href: type: string example: >- https://api.shipstation.com/v2/fulfillments?page=3&page_size=100 prev: type: object properties: href: type: string example: >- https://api.shipstation.com/v2/fulfillments?page=1&page_size=100 next: type: object properties: href: type: string example: >- https://api.shipstation.com/v2/fulfillments?page=3&page_size=100 '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' post: summary: Create fulfillments description: > Create one or more fulfillments by marking shipments as shipped with tracking information. This will notify customers and marketplaces according to your configuration. tags: - fulfillments operationId: create_fulfillments requestBody: required: true content: application/json: schema: type: object required: - fulfillments properties: fulfillments: type: array items: type: object required: - shipment_id - tracking_number - carrier_code properties: shipment_id: type: string description: The shipment id to fulfill example: se-12345678 tracking_number: type: string description: Tracking number for the shipment example: 1Z12345E1234567890 carrier_code: type: string description: Carrier code (e.g., "ups", "fedex", "usps") example: ups ship_date: type: string format: date-time description: Ship date (defaults to current date if not provided) example: '2024-01-15T10:00:00Z' notify_customer: type: boolean description: Whether to notify the customer via email example: true notify_order_source: type: boolean description: Whether to notify the order source/marketplace example: true responses: '200': description: Fulfillments processed (check has_errors and individual results) content: application/json: schema: type: object properties: has_errors: type: boolean description: Indicates if any fulfillments failed to create example: false fulfillments: type: array items: type: object properties: shipment_id: type: string description: The shipment ID that was processed example: se-12345678 shipment_number: type: string description: The shipment number (order number) example: ORDER-001 error_message: type: - string - 'null' description: Error message if creation failed (null on success) example: null '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/ServerError' /v2/labels: x-visibility: public summary: Print shipping labels description: > Print shipping labels for any of the top global carriers in minutes. Simply connect your existing carrier accounts in the API dashboard, and start creating labels. get: summary: List labels description: > This method returns a list of labels that you've created. 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 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. - $ref: '#/components/parameters/carrier_id_query_param' description: Only return labels for a specific carrier account. - $ref: '#/components/parameters/tracking_number_query_param' description: Only return labels with a specific tracking number. - $ref: '#/components/parameters/batch_id_query_param' description: Only return labels that were created in a specific batch. - $ref: '#/components/parameters/rate_id_query_param' - $ref: '#/components/parameters/shipment_id_query_param' - $ref: '#/components/parameters/warehouse_id_query_param' description: Only return labels that originate from a specific warehouse. - $ref: '#/components/parameters/created_at_start_query_param' description: >- Only return labels that were created on or after a specific date/time. - $ref: '#/components/parameters/created_at_end_query_param' description: >- Only return labels that were created on or before a specific date/time. - $ref: '#/components/parameters/page_query_param' - $ref: '#/components/parameters/page_size_query_param' - $ref: '#/components/parameters/sort_dir_query_param' - 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/BadRequest' '500': $ref: '#/components/responses/ServerError' 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/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/labels/rates/{rate_id}: x-visibility: public 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: - $ref: '#/components/parameters/rate_id_path_param' 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/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/labels/shipment/{shipment_id}: x-visibility: public 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: - $ref: '#/components/parameters/shipment_id_path_param' 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/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/labels/{label_id}: x-visibility: public summary: Label description: Retrieve a specific label by its label id. parameters: - $ref: '#/components/parameters/label_id_path_param' get: summary: Get label by id description: Retrieve a specific label by its label id. tags: - labels operationId: get_label_by_id parameters: - $ref: '#/components/parameters/label_download_type_query_param' 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/BadRequest' '404': description: >- The API returns a 404 response when no `label` corresponds to the `label_id` provided. content: application/json: schema: title: empty_response_body type: string minLength: 0 maxLength: 0 '500': $ref: '#/components/responses/ServerError' /v2/labels/{label_id}/return: x-visibility: public summary: >- Return labels. This currently creates a return for all SKUs on the referenced label. parameters: - $ref: '#/components/parameters/label_id_path_param' post: summary: Create a return label description: >- Create a return label for a previously created outbound label. The return label will automatically swap the ship to and ship from addresses from the original 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/BadRequest' '404': description: >- The API returns a 404 response when no `label` corresponds to the `label_id` provided. content: application/json: schema: title: empty_response_body type: string minLength: 0 maxLength: 0 '500': $ref: '#/components/responses/ServerError' /v2/labels/{label_id}/track: x-visibility: public summary: Tracking a label description: >- Carriers will provide tracking information so you can monitor the status of your shipment. parameters: - $ref: '#/components/parameters/label_id_path_param' get: summary: Get label tracking information description: Retrieve the label's tracking details. 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/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/labels/{label_id}/void: x-visibility: public summary: Label voiding description: > Some carriers charge for creating a label upon purchase vs upon use. The ShipStation API allows you to void a label to get a refund. parameters: - $ref: '#/components/parameters/label_id_path_param' put: summary: Void a label by id description: >- Void a specific label using its label id. For labels that are paid for at time of label creation, this will also request a refund from the carrier. 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/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/manifests: x-visibility: public 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: - $ref: '#/components/parameters/warehouse_id_query_param' - 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 - $ref: '#/components/parameters/created_at_start_query_param' - $ref: '#/components/parameters/created_at_end_query_param' - $ref: '#/components/parameters/carrier_id_query_param' - $ref: '#/components/parameters/page_query_param' - $ref: '#/components/parameters/page_size_query_param' - $ref: '#/components/parameters/label_ids_query_param' responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/list_manifests_response_body' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' post: summary: Create manifest description: > Each ShipStation 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: title: create_manifest_request_body oneOf: - $ref: '#/components/schemas/create_manifest_by_object_request_body' - $ref: '#/components/schemas/create_manifest_label_ids_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/BadRequest' '500': $ref: '#/components/responses/ServerError' /v2/manifests/{manifest_id}: x-visibility: public summary: Manifest id description: Manifest ID parameters: - $ref: '#/components/parameters/manifest_id_path_param' 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/BadRequest' '404': description: >- The API returns a 404 response when no `manifest` corresponds to the `manifest_id` provided. content: application/json: schema: $ref: '#/components/schemas/error_response_body' '500': $ref: '#/components/responses/ServerError' /v2/packages: x-visibility: public 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/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' 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/BadRequest' '500': $ref: '#/components/responses/ServerError' /v2/packages/{package_id}: x-visibility: public summary: Package description: Create, edit, and delete individual custom packages. parameters: - $ref: '#/components/parameters/package_id_path_param' 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/BadRequest' '404': description: >- The API returns a 404 response when no `package` corresponds to the `package_id` provided. content: application/json: schema: title: empty_response_body type: string minLength: 0 maxLength: 0 '500': $ref: '#/components/responses/ServerError' 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': $ref: '#/components/responses/NoContent' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' delete: summary: Delete a custom package by id description: Delete a custom package using the ID tags: - package_types operationId: delete_package_typ responses: '204': $ref: '#/components/responses/NoContent' '400': description: >- The API returns a 400 response when no `package` corresponds to the `package_id` provided. content: application/json: schema: title: empty_response_body type: string minLength: 0 maxLength: 0 '404': description: >- The API returns a 404 response when no `package` corresponds to the `package_id` provided. content: application/json: schema: title: empty_response_body type: string minLength: 0 maxLength: 0 '500': $ref: '#/components/responses/ServerError' /v2/pickups: x-visibility: public 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: - $ref: '#/components/parameters/carrier_id_query_param' - $ref: '#/components/parameters/warehouse_id_query_param' - $ref: '#/components/parameters/created_at_start_query_param' description: >- Only return scheduled pickups that were created on or after a specific date/time - $ref: '#/components/parameters/created_at_end_query_param' description: >- Only return scheduled pickups that were created on or before a specific date/time - $ref: '#/components/parameters/page_query_param' - $ref: '#/components/parameters/page_size_query_param' responses: '200': description: The request was a success. content: application/json: schema: title: get_pickups_response_body allOf: - $ref: '#/components/schemas/list_pickup_response_body' - $ref: '#/components/schemas/error_response_body' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' 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: title: schedule_pickup_response_body allOf: - $ref: '#/components/schemas/schedule_pickup_response_body' - $ref: '#/components/schemas/error_response_body' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/pickups/{pickup_id}: x-visibility: public summary: Scheduled pickup description: | A package pickup that has been scheduled with a carrier parameters: - $ref: '#/components/parameters/pickup_id_path_param' 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: title: get_pickup_by_id_response_body allOf: - $ref: '#/components/schemas/pickup_response_body' - $ref: '#/components/schemas/error_response_body' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' 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: title: delete_pickup_by_id_response_body allOf: - $ref: '#/components/schemas/error_response_body' - $ref: '#/components/schemas/delete_scheduled_pickup_response_body' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/rates: x-visibility: public 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/BadRequest' '500': $ref: '#/components/responses/ServerError' /v2/rates/estimate: x-visibility: public 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/BadRequest' '500': $ref: '#/components/responses/ServerError' /v2/rates/{rate_id}: x-visibility: public summary: Rate description: Get Individual rate information. parameters: - $ref: '#/components/parameters/rate_id_path_param' 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/BadRequest' '404': description: >- The API returns a 404 response when no `rate` corresponds to the `rate_id` provided. content: application/json: schema: $ref: '#/components/schemas/error_response_body' '500': $ref: '#/components/responses/ServerError' /v2/shipments: x-visibility: public summary: Shipments description: > Shipments are the gatekeeper to more advanced functionality inside ShipStation. When you create a shipment, we respond with a shipment_id that is a unique identifier inside of ShipStation. 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' - $ref: '#/components/parameters/batch_id_query_param' - $ref: '#/components/parameters/pickup_id_query_param' - $ref: '#/components/parameters/created_at_start_query_param' - $ref: '#/components/parameters/created_at_end_query_param' - $ref: '#/components/parameters/modified_at_start_query_param' - $ref: '#/components/parameters/modified_at_end_query_param' - $ref: '#/components/parameters/page_query_param' - $ref: '#/components/parameters/page_size_query_param' - $ref: '#/components/parameters/sales_order_id_query_param' - $ref: '#/components/parameters/sort_dir_query_param' - $ref: '#/components/parameters/shipment_number_query_param' - $ref: '#/components/parameters/ship_to_name_query_param' - $ref: '#/components/parameters/item_keyword_query_param' - $ref: '#/components/parameters/payment_date_start_query_param' - $ref: '#/components/parameters/payment_date_end_query_param' - $ref: '#/components/parameters/store_id_query_param' - $ref: '#/components/parameters/external_shipment_id_query_param' - 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/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' post: summary: Create shipments description: Create one or more shipments tags: - shipments operationId: create_shipments requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/create_shipments_request_body' responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/create_shipments_response_body' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/ServerError' /v2/shipments/external_shipment_id/{external_shipment_id}: x-visibility: public summary: External shipment id description: > When a shipment object is created with a custom shipment ID, you can query it using this endpoint parameters: - $ref: '#/components/parameters/external_shipment_id_path_param' get: summary: Get shipment by external id description: >- Query Shipments created using your own custom ID convention using this endpoint 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/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/shipments/{shipment_id}: x-visibility: public summary: Get and Update Shipment description: Retrieve and Update and individual shipment based on its ID parameters: - $ref: '#/components/parameters/shipment_id_path_param' 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/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/shipments/{shipment_id}/cancel: x-visibility: public summary: Cancel shipment description: Cancel a Shipment parameters: - $ref: '#/components/parameters/shipment_id_path_param' 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': $ref: '#/components/responses/NoContent' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/shipments/{shipment_id}/rates: x-visibility: public 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: - $ref: '#/components/parameters/shipment_id_path_param' get: summary: Get shipment rates description: Get Rates for the shipment information associated with the shipment ID tags: - shipments operationId: list_shipment_rates parameters: - $ref: '#/components/parameters/created_at_start_query_param' responses: '200': description: The request was a success. content: application/json: schema: $ref: '#/components/schemas/list_shipment_rates_response_body' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/shipments/{shipment_id}/tags/{tag_name}: x-visibility: public summary: Shipment tags description: > Tags associated with the shipment object to be used to organize and query shipment items. parameters: - $ref: '#/components/parameters/shipment_id_path_param' - $ref: '#/components/parameters/tag_name_path_param' 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/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' delete: summary: Remove tag from shipment description: Remove an existing tag from the Shipment object tags: - shipments operationId: untag_shipment responses: '204': $ref: '#/components/responses/NoContent' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/tags: x-visibility: public 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] 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/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/tags/{tag_name}: x-visibility: public summary: Tag description: Create and delete tags parameters: - $ref: '#/components/parameters/tag_name_path_param' 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/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/tracking/stop: x-visibility: public 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: - $ref: '#/components/parameters/carrier_code_query_param' - $ref: '#/components/parameters/tracking_number_query_param' responses: '204': $ref: '#/components/responses/NoContent' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/warehouses: x-visibility: public 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], 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/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/warehouses/{warehouse_id}: x-visibility: public 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], then you can simply pass the warehouse_id instead. parameters: - $ref: '#/components/parameters/warehouse_id_path_param' 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/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/environment/webhooks: x-visibility: public summary: Webhooks description: > ShipStation exposes asynchronous operations for long running operations such as batch labels and rates. Webhooks allow the ShipStation 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/BadRequest' '500': $ref: '#/components/responses/ServerError' post: summary: Create a webhook description: Create a webhook 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/BadRequest' '409': $ref: '#/components/responses/conflict' '500': $ref: '#/components/responses/ServerError' /v2/environment/webhooks/{webhook_id}: x-visibility: public summary: Webhook description: Retrieve, update, and delete information for individual webhooks parameters: - $ref: '#/components/parameters/webhook_id_path_param' 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/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' 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': $ref: '#/components/responses/NoContent' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' delete: summary: Delete webhook by id description: Delete a webhook tags: - webhooks operationId: delete_webhook responses: '204': $ref: '#/components/responses/NoContent' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/users: x-visibility: public summary: Users description: > Manage and retrieve user information for the ShipStation account. This endpoint allows you to list users with various filtering options. get: operationId: listUsers summary: List users tags: - users parameters: - name: status description: Filter users by their status in: query required: false schema: type: string enum: - active - inactive - locked_out - email_lock example: active - name: page_size description: The number of results to return per page in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 25 example: 25 - name: page description: The page number to return in: query required: false schema: type: integer minimum: 1 default: 1 example: 1 responses: '200': description: List of users content: application/json: schema: type: object properties: users: type: array items: type: object properties: user_id: type: string description: Unique identifier for the user example: 123abc4d-1a2b-4321-a1b2-123abc4d5e6f name: type: string description: Full name of the user example: First Last username: type: string description: Username for the user example: user.name email: type: string format: email description: Email address of the user example: user.name@company.com status: type: string description: Current status of the user example: Active last_login_at: type: string description: Date of the user's last login example: '2025-01-01' created_at: type: string description: Date when the user was created example: '2023-05-28' total: type: integer description: Total number of users example: 75 page: type: integer description: Current page number example: 1 pages: type: integer description: Total number of pages example: 3 links: type: object properties: first: type: object properties: href: type: string description: URL to the first page example: >- https://api.shipstation.com/v2/users?page=1&page_size=25 last: type: object properties: href: type: string description: URL to the last page example: >- https://api.shipstation.com/v2/users?page=3&page_size=25 prev: type: object properties: href: type: string description: URL to the previous page example: >- https://api.shipstation.com/v2/users?page=1&page_size=25 next: type: object properties: href: type: string description: URL to the next page example: >- https://api.shipstation.com/v2/users?page=2&page_size=25 '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /v2/products: x-visibility: public summary: Products description: > Manage products in your ShipStation account. Products represent the items you sell and ship to customers. get: operationId: listProducts summary: List products tags: - products parameters: - name: sku description: Filter products by SKU in: query required: false schema: type: string example: TEST-SKU-001 - name: name description: Filter products by name in: query required: false schema: type: string example: Test Product - name: active description: Filter products by active status in: query required: false schema: type: boolean example: true - name: page_size description: The number of results to return per page in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 100 example: 25 - name: page description: The page number to return in: query required: false schema: type: integer minimum: 1 default: 1 example: 5 responses: '200': description: List of products content: application/json: schema: type: object properties: products: type: array items: type: object properties: product_id: type: integer description: Unique identifier for the product example: 10736794 sku: type: string description: Stock Keeping Unit identifier example: K1 name: type: string description: Product name example: Test Product upc: type: - string - 'null' description: Universal Product Code example: 123-4 thumbnail_url: type: - string - 'null' description: URL to product thumbnail image example: www.image.com price: type: object properties: currency: type: string description: Currency code example: usd amount: type: number description: Price amount example: 88 dimensions: type: object properties: unit: type: string description: Unit of measurement example: inch length: type: number description: Length dimension example: 9 width: type: number description: Width dimension example: 5 height: type: number description: Height dimension example: 7 weight: type: object properties: value: type: number description: Weight value example: 99.2 unit: type: string description: Weight unit example: ounce internal_notes: type: - string - 'null' description: Internal notes about the product example: Describe your item fulfillment_sku: type: - string - 'null' description: Fulfillment SKU example: widget-2 create_date: type: string format: date-time description: Date when product was created example: '2025-07-07T20:10:02.13Z' modify_date: type: string format: date-time description: Date when product was last modified example: '2025-07-07T20:10:02.13Z' active: type: boolean description: Whether the product is active example: true product_category: type: - object - 'null' properties: product_category_id: type: integer example: 26663 name: type: string example: Example-category preset_group: type: - string - 'null' description: Preset group example: Default warehouse_location: type: - string - 'null' description: Warehouse location example: BIN 43-6 default_carrier_code: type: - string - 'null' description: Default carrier code example: stamps_com default_service_code: type: - string - 'null' description: Default service code example: usps_first_class_mail default_package_code: type: - string - 'null' description: Default package code example: large_flat_rate_box default_intl_carrier_code: type: - string - 'null' description: Default international carrier code example: stamps_com default_intl_service_code: type: - string - 'null' description: Default international service code example: usps_priority_mail_international default_intl_package_code: type: - string - 'null' description: Default international package code example: package default_confirmation: type: - string - 'null' description: Default confirmation type example: none default_intl_confirmation: type: - string - 'null' description: Default international confirmation type example: delivery customs_description: type: - string - 'null' description: Customs description example: An object going internationally customs_value: type: - number - 'null' description: Customs value example: 20 customs_tariff_no: type: - string - 'null' description: Customs tariff number example: 0245.56.13 customs_country_code: type: - string - 'null' description: Customs country code example: US no_customs: type: boolean description: Whether customs is required example: false tags: type: - array - 'null' items: type: object properties: tag_id: type: integer example: 21121 name: type: string example: Sample Tag color: type: string example: '#800080' aliases: type: - array - 'null' items: type: object properties: store_id: type: integer example: 2095811 sku_alias: type: string example: alt-sku product_type: type: - string - 'null' description: Product type example: standalone is_returnable: type: boolean description: Whether the product is returnable example: false should_override_name: type: - boolean - 'null' description: Whether to override the product name example: true is_bundle: type: - boolean - 'null' description: Whether the product is a bundle example: true bundle_components: type: - array - 'null' items: type: object properties: bundle_product_id: type: integer example: 10736791 component_product_id: type: integer example: 10408926 sku: type: string example: New-SKU quantity: type: integer example: 3 active: type: boolean example: true auto_split_option: type: string description: Auto split option example: do_not_split auto_split_custom_quantity: type: - integer - 'null' description: Auto split custom quantity example: 3 total: type: integer description: Total number of products example: 510 page: type: integer description: Current page number example: 5 pages: type: integer description: Total number of pages example: 6 links: type: object properties: first: type: object properties: href: type: string description: URL to the first page example: >- https://api.shipstation.com/v2/products?page=1&page_size=100 last: type: object properties: href: type: string description: URL to the last page example: >- https://api.shipstation.com/v2/products?page=6&page_size=100 prev: type: object properties: href: type: string description: URL to the previous page example: >- https://api.shipstation.com/v2/products?page=4&page_size=100 next: type: object properties: href: type: string description: URL to the next page example: >- https://api.shipstation.com/v2/products?page=6&page_size=100 '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' tags: - name: batches description: > Process labels in bulk and receive a large number of labels and customs forms in bulk responses. Batching is ideal for workflows that need to process hundreds or thousands of labels quickly. x-displayName: Batches - name: carriers description: > Retreive useful details about the carriers connected to your accounts, including carrier IDs, service IDs, advanced options, and available carrier package types. x-displayName: Carriers - name: downloads description: | Download your label files in PDF, PNG, and ZPL. x-displayName: Downloads - name: fulfillments description: > Manage fulfillments which represent completed shipments. Create fulfillments to mark orders as shipped with tracking information and notify customers and marketplaces. x-displayName: Fulfillments - name: inventory description: | Manage inventory, adjust quantities, and handle warehouses and locations. x-displayName: Inventory - name: labels description: > Purchase and print shipping labels for any carrier active on your account. The labels endpoint also supports creating return labels, voiding labels, and getting label details like tracking. x-displayName: Labels - name: manifests description: > A manifest is a document that provides a list of the day's shipments. It typically contains a barcode that allows the pickup driver to scan a single document to register all shipments, rather than scanning each shipment individually. x-displayName: Manifests - name: package_pickups description: Scheduled pickups and manage pickup requests for supported carriers. x-displayName: Package Pickups - name: package_types description: > Create custom package types to use for your shipments, rather than the carriers' default package types. x-displayName: Package Types - name: products description: > Manage products in your ShipStation account. Products represent the items you sell and ship to customers. x-displayName: Products - name: rates description: > Quickly compare rates using the Rates endpoint. You can see and compare rates for the carriers connected to your account (as long as they support sending rates). x-displayName: Rates - name: shipments description: > Shipments are at the core of most ShipStation capabilities. Shipment objects are required for cretaing labels and manifests, as well as getting rates. x-displayName: Shipments - name: tags description: > Tags are text-based identifiers you can add to shipments to help in your shipment management workflows. x-displayName: Tags - name: tracking description: > Use the tracking endpoint to stop receiving tracking updates (more dedicated tracking endpoint methods coming soon). x-displayName: Tracking - name: warehouses description: > Get warehouse details like warehouse ID and related addresses using the warehouses endpoint. x-displayName: Warehouses - name: users description: > Manage and retrieve user information for the ShipStation account. This endpoint allows you to list users with various filtering options. x-displayName: Users - name: webhooks description: > Webhooks are a powerful feature that can save you from sending repeated polling requests to check on the state of something. With webhooks, ShipStation will automatically contact your servers when the stage changes. This can include parcel tracking events, notification when a batch operation completes, and more. x-displayName: Webhooks components: securitySchemes: api_keys: description: | Generate your secret API key in the app settings. name: api-key type: apiKey in: header schemas: fulfillment: title: fulfillment type: object description: A fulfillment represents a completed shipment with tracking information properties: fulfillment_id: type: string description: Unique identifier for the fulfillment example: se-12345678 shipment_id: type: string description: The associated shipment id example: se-12345678 shipment_number: type: string description: The shipment number (order number) example: ORDER-001 user_id: type: string description: The user id that created this fulfillment example: 00000000-0000-0000-0000-000000000000 tracking_number: type: string description: Tracking number for the shipment example: 1Z12345E1234567890 created_at: type: string format: date-time description: Date and time when the fulfillment was created example: '2024-01-15T10:30:00Z' ship_date: type: string format: date-time description: Date when the shipment was shipped example: '2024-01-15T00:00:00Z' voided_at: type: - string - 'null' format: date-time description: Date and time when the fulfillment was voided example: '2024-01-15T00:00:00Z' delivered_at: type: - string - 'null' format: date-time description: Date and time when the shipment was delivered example: '2024-01-18T14:22:00Z' fulfillment_carrier_friendly_name: type: string description: Friendly name of the carrier example: UPS fulfillment_provider_id: type: - string - 'null' description: Fulfillment provider ID example: se-12345678 fulfillment_provider_friendly_name: type: - string - 'null' description: Friendly name of the fulfillment provider example: ShipStation Fulfillment fulfillment_provider_code: type: - string - 'null' description: Code of the fulfillment provider example: shipstation_fulfillment fulfillment_service_code: type: - string - 'null' description: Service code used for fulfillment example: ups_ground fulfillment_fee: type: object description: Fee charged for the fulfillment properties: amount: type: number description: Fee amount example: 12.5 currency: type: string description: Currency code example: usd void_requested: type: boolean description: Whether a void has been requested for this fulfillment example: false voided: type: boolean description: Whether this fulfillment has been voided example: false order_source_notified: type: boolean description: Whether the order source has been notified example: true notification_error_message: type: - string - 'null' description: Error message if notification failed example: null ship_to: type: object description: Shipping address information properties: name: type: string description: Recipient name example: Jane Doe company_name: type: - string - 'null' description: Company name example: Example Corp email: type: - string - 'null' description: Email address example: jane@example.com phone: type: - string - 'null' description: Phone number example: 555-555-5555 address_line1: type: string description: Street address line 1 example: 525 S Winchester Blvd address_line2: type: - string - 'null' description: Street address line 2 example: null address_line3: type: - string - 'null' description: Street address line 3 example: null city_locality: type: string description: City or locality example: San Jose state_province: type: string description: State or province example: CA postal_code: type: string description: Postal or ZIP code example: '95128' country_code: type: string description: ISO country code example: US 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 example: se-1234567 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 x-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 x-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. example: true estimated_delivery_date: readOnly: true allOf: - $ref: '#/components/schemas/date' carrier_delivery_days: type: string readOnly: true minLength: 1 example: '22' description: The carrier delivery days ship_date: type: string format: date-time readOnly: true minLength: 1 example: '2024-12-23T00:00:00.000Z' description: ship date negotiated_rate: type: boolean readOnly: true description: Indicates if the rates been negotiated example: true service_type: type: string readOnly: true minLength: 1 example: next_day description: service type service_code: type: string readOnly: true minLength: 1 example: usps_priority_mail_express description: service code for the rate trackable: type: boolean readOnly: true description: Indicates if rate is trackable example: true carrier_code: type: string readOnly: true minLength: 1 example: stamps_com description: >- A [shipping carrier] , such as `fedex`, `dhl_express`, `stamps_com`, etc. carrier_nickname: type: string readOnly: true minLength: 1 example: free description: carrier nickname carrier_friendly_name: type: string readOnly: true minLength: 1 example: free description: carrier friendly name validation_status: readOnly: true allOf: - $ref: '#/components/schemas/validation_status' example: valid warning_messages: type: array readOnly: true minItems: 0 items: type: string readOnly: true minLength: 0 example: warning description: warning message description: The warning messages error_messages: type: array readOnly: true minItems: 0 items: type: string readOnly: true minLength: 0 example: error description: error message description: The error messages label: title: label type: object description: > A label represents the physical sticker that you affix to a package to ship it. ShipStation makes it easy for you to [create labels] 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 ShipStation when the label is created. example: se-123456 status: readOnly: true allOf: - $ref: '#/components/schemas/label_status' example: completed shipment_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: > The shipment that this label is for. ShipStation can create a shipment for you automatically when you [create a label], or you can [create your own shipment] and then [use it to print a label] example: se-1234567 external_shipment_id: readOnly: true type: string maxLength: 50 x-nullable: true example: externalId-1234556 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. external_order_id: readOnly: true type: string x-nullable: true example: externalOrderId-1232434 description: ID that the Order Source assigned 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. ShipStation 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 ShipStation . 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 example: true 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 x-nullable: true example: asd12323 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 example: 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], 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] that was used to create this label example: se-1234567 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] 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 example: 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], 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: no_validation allOf: - $ref: '#/components/schemas/validate_address' voided: type: boolean readOnly: true example: true description: | Indicates whether the label has been [voided] voided_at: x-nullable: true readOnly: true allOf: - $ref: '#/components/schemas/date_time' description: > The date and time that the label was [voided] , 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 example: 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: x-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] who will ship the package, such as `fedex`, `dhl_express`, `stamps_com`, etc. confirmation: readOnly: true default: none allOf: - $ref: '#/components/schemas/delivery_confirmation' description: >- The type of delivery confirmation that is required for this shipment. 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 x-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. qr_code_download: readOnly: true x-nullable: true allOf: - $ref: '#/components/schemas/optional_link' description: The QR code download for the package paperless_download: readOnly: true x-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 x-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/label_package' - title: alternative_identifiers type: object additionalProperties: false properties: alternative_identifiers: type: array readOnly: true x-nullable: true description: | Alternative identifiers associated with this package. items: $ref: '#/components/schemas/alternative_identifier' alternative_identifiers: type: array readOnly: true x-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' rate_details: type: array readOnly: true items: type: object properties: rate_detail_type: type: string example: shipping carrier_description: type: string example: Shipping carrier_billing_code: type: string example: shipping carrier_memo: type: string example: '' amount: type: object allOf: - $ref: '#/components/schemas/monetary_value' billing_source: type: string example: carrier description: Rate details associate to the label. tracking_url: readOnly: true x-nullable: true type: string example: https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234 description: > The URL to track the package. This URL is provided by the carrier and is unique to the tracking number. ship_to: readOnly: true allOf: - $ref: '#/components/schemas/shipping_address_to' description: The recipient's mailing address batch: title: batch type: object description: > Batches are an advanced feature of ShipStation 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. example: '123456' external_batch_id: type: string readOnly: true x-nullable: true minLength: 0 example: 12323aaaar description: A string that uniquely identifies the external batch batch_notes: type: string readOnly: true x-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 ShipStation processed_at: x-nullable: true readOnly: true allOf: - $ref: '#/components/schemas/date_time' description: The date and time the batch was processed in ShipStation errors: type: integer format: int32 readOnly: true minimum: 0 example: 2 description: The number of errors that occurred while generating the batch process_errors: 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' 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 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 name: type: string description: The name of the webhook example: My Webhook store_id: type: integer description: Store ID example: 123456 webhook_header: title: webhook_header type: object description: Optional header to be specified in webhook properties: key: title: key type: string description: Key/name of a header example: custom-key value: title: value type: string description: Value of a header example: custom-value required: - key - value 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: x-nullable: true type: boolean default: false example: true 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 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. example: se-28529731 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 x-nullable: true description: Provides a helpful description for the custom package. 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`. 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 example: child minLength: 1 description: >- The type of resource, or the type of relationship to the parent resource 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. 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 - created_at - modified_at - shipment_status - ship_to - ship_from - return_to - confirmation - advanced_options - insurance_provider - tags - packages - total_weight additionalProperties: false allOf: - $ref: '#/components/schemas/partial_shipment' 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: - title: validate_shipment_fields type: object properties: validate_address: default: no_validation allOf: - $ref: '#/components/schemas/validate_address' - $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: x-nullable: true allOf: - $ref: '#/components/schemas/se_id' description: The carrier account that is billed for the shipping charges example: se-1234567 service_code: x-nullable: true allOf: - $ref: '#/components/schemas/service_code' description: > The [carrier service] used to ship the package, such as `fedex_ground`, `usps_first_class_mail`, `flat_rate_envelope`, etc. example: se_1234567 requested_shipment_service: type: string x-nullable: true description: The requested shipment service example: usps_priority_mail shipping_rule_id: x-nullable: true allOf: - $ref: '#/components/schemas/se_id' description: > ID of the shipping rule, which you want to use to automate carrier/carrier service selection for the shipment example: se-1234 external_order_id: type: string x-nullable: true example: '1232434' description: ID that the Order Source assigned hold_until_date: type: string format: date-time x-nullable: true description: Date to hold the shipment until example: '2025-01-15T00:00:00.000Z' ship_by_date: type: string format: date-time x-nullable: true description: Date by which the shipment should be shipped example: '2025-01-15T00:00:00.000Z' retail_rate: x-nullable: true allOf: - $ref: '#/components/schemas/monetary_value' description: The retail rate for the shipment store_id: readOnly: false allOf: - $ref: '#/components/schemas/se_id' description: The store ID associated with the shipment example: se-12345 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 notes_from_buyer: type: string x-nullable: true description: Notes from the buyer example: Please handle with care notes_for_gift: type: string x-nullable: true description: Gift notes example: Happy Birthday! is_gift: type: boolean default: false description: Indicates if the shipment is a gift example: true assigned_user: type: string x-nullable: true description: User assigned to the shipment example: user@example.com amount_paid: allOf: - $ref: '#/components/schemas/monetary_value' description: Total amount paid for the order shipping_paid: allOf: - $ref: '#/components/schemas/monetary_value' description: Amount paid for shipping tax_paid: allOf: - $ref: '#/components/schemas/monetary_value' description: Amount paid for taxes zone: type: integer format: int32 x-nullable: true minimum: 0 description: Shipping zone example: 1 display_scheme: type: string x-nullable: true description: Display scheme for the shipment example: label tax_identifiers: type: array x-nullable: true items: allOf: - $ref: '#/components/schemas/tax_identifier' external_shipment_id: type: string maxLength: 50 x-nullable: true example: '1234556' 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 x-nullable: true readOnly: false example: '10001' 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: x-nullable: true allOf: - $ref: '#/components/schemas/date' description: > The date that the shipment was (or will be) shippped. ShipStation 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 ShipStation . 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]. Then you can simply specify the `warehouse_id` rather than the complete address each time. warehouse_id: x-nullable: true default: null allOf: - $ref: '#/components/schemas/se_id' description: > The [warehouse] that the shipment is being shipped from. Either `warehouse_id` or `ship_from` must be specified. return_to: readOnly: false allOf: - $ref: '#/components/schemas/shipping_address' description: > The return address for this shipment. Defaults to the `ship_from` address. Can be sent with a warehouse_id, in which case the return address can be overridden. This allows you to have a different address printed on the label while maintaining the origin address. is_return: type: boolean x-nullable: true default: false description: > An optional indicator if the shipment is intended to be a return. Defaults to false if not provided. example: true confirmation: default: none allOf: - $ref: '#/components/schemas/delivery_confirmation' description: The type of delivery confirmation that is required for this shipment customs: x-nullable: true default: null allOf: - $ref: '#/components/schemas/international_shipment_options' description: > Customs information. This is usually only needed for international shipments. advanced_options: readOnly: false 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: false 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. Note: Tags require object structure with name property, not simple strings. 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/weigth' description: The combined weight of all packages in the shipment comparison_rate_type: x-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 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' - 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 link: title: link type: object description: A link to a related resource additionalProperties: false required: - href allOf: - $ref: '#/components/schemas/optional_link' 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' description: Currency code amount: type: number minimum: 0 description: The monetary amount, in the specified currency. example: 12 estimated_import_charges: title: estimated_import_charges type: object description: > Estimated import charges for commercial invoices for international shipments. additionalProperties: false properties: taxes: allOf: - $ref: '#/components/schemas/monetary_value' description: Estimated import taxes. duties: allOf: - $ref: '#/components/schemas/monetary_value' description: Estimated import duties. 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 x-nullable: true description: | Additional text about how to handle the shipment at this address. example: any instructions 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' 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 x-nullable: true example: example@example.com description: | Email for the address owner. company_name: type: string minLength: 1 x-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 x-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 x-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: 'yes' description: Indicates whether this is a residential address. allOf: - $ref: '#/components/schemas/address_residential_indicator' 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 ShipStation . cancelled_at: readOnly: true allOf: - $ref: '#/components/schemas/date_time' description: The date and time that the pickup was cancelled in ShipStation . carrier_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: The carrier_id associated with the pickup example: se-1234567 confirmation_number: readOnly: true type: string x-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: title: contact_details type: object required: - name - email - phone properties: name: type: string minLength: 1 example: Jonh email: allOf: - $ref: '#/components/schemas/email' example: email@email.com phone: type: string minLength: 7 description: Phone number associated example: '89876752562' pickup_notes: type: string minLength: 0 description: >- Used by some carriers to give special instructions for a package pickup example: call before 15:00 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: readOnly: true type: array description: > An array of available pickup windows. Carriers can return multiple times that they will pickup packages. items: allOf: - title: pickup_windows type: object properties: start_at: allOf: - $ref: '#/components/schemas/date_time' end_at: allOf: - $ref: '#/components/schemas/date_time' 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' description: Dimension unit length: type: number minimum: 0 default: 0 example: 2 description: The length of the package, in the specified unit width: type: number minimum: 0 default: 0 example: 2 description: The width of the package, in the specified unit height: type: number minimum: 0 default: 0 example: 1 description: The height of the package, in the specified unit weigth: title: weight type: object description: The weight of a package required: - value - unit additionalProperties: false properties: value: type: number minimum: 0 exclusiveMinimum: 2 description: The weight, in the specified unit example: 3 unit: allOf: - $ref: '#/components/schemas/weight_unit' example: pound description: Weight unit 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 example: se-1234567 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 x-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 x-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. example: true estimated_delivery_date: readOnly: true allOf: - $ref: '#/components/schemas/date' example: '2024-12-23T00:00:00.000Z' carrier_delivery_days: type: string readOnly: true minLength: 1 example: '22' description: The carrier delivery days ship_date: type: string format: date-time readOnly: true minLength: 1 example: 10/22/2024z00:00 description: ship date negotiated_rate: type: boolean readOnly: true description: Indicates if the rates been negotiated example: true service_type: type: string readOnly: true minLength: 1 example: next_day description: service type service_code: type: string readOnly: true minLength: 1 description: service code for the rate example: usps_priority_mail_express trackable: type: boolean readOnly: true description: Indicates if rate is trackable example: true carrier_code: type: string readOnly: true minLength: 1 description: carrier code example: stamps_com carrier_nickname: type: string readOnly: true minLength: 1 example: Free description: carrier nickname carrier_friendly_name: type: string readOnly: true minLength: 1 example: free 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 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 example: se-1234567 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 example: true description: Supports domestic shipping international: type: boolean readOnly: true example: true description: Supports international shipping. is_multi_package_supported: type: boolean example: true readOnly: true description: Carrier supports multiple packages per shipment 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. 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: x-nullable: true readOnly: true allOf: - $ref: '#/components/schemas/address' description: The matched address found by the ShipStation API messages: type: array readOnly: true default: [] items: 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: x-nullable: true allOf: - $ref: '#/components/schemas/address_validation_detail_code' description: >- The list of messages that were generated during the address validation request. label_package: title: label_package type: object description: | A package returned in the response from creating a [shipping label] required: - weight additionalProperties: false properties: package_id: readOnly: true type: integer format: int32 description: The shipment package id example: 1234545 package_code: allOf: - $ref: '#/components/schemas/package_code' description: > The [package type], such as `thick_envelope`, `small_flat_rate_box`, `large_package`, etc. The code `package` indicates a custom or unknown package type. 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_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 qr_code_download: readOnly: true allOf: - $ref: '#/components/schemas/optional_link' description: The QR code download for the package paperless_download: readOnly: true allOf: - $ref: '#/components/schemas/paperless_download' description: >- The paperless details which may contain elements like `href`, `instructions` and `handoff_code`. label_messages: allOf: - $ref: '#/components/schemas/label_messages' external_package_id: type: string minLength: 1 description: An external package id. example: se-1234567 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 x-nullable: true sequence: readOnly: true format: int32 type: integer description: Package sequence example: 34 has_label_documents: type: boolean description: Whether the package has label documents available for download example: true has_form_documents: type: boolean description: Whether the package has form documents available for download example: true has_qr_code_documents: type: boolean description: Whether the package has QR code documents available for download example: true has_paperless_label_documents: type: boolean description: Whether the package has paperless documents available for download example: true package: title: package type: object description: | A package associated with a shipment required: - weight additionalProperties: false properties: shipment_package_id: allOf: - $ref: '#/components/schemas/se_id' readOnly: true description: A string that uniquely identifies this shipment package example: se-123456 package_id: allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies this [package type] example: se-123456 package_code: allOf: - $ref: '#/components/schemas/package_code' description: > The [package type] such as `thick_envelope`, `small_flat_rate_box`, `large_package`, etc. The code `package` indicates a custom or unknown package type. example: thick_envelope package_name: type: string description: The name of the of the [package type] example: Flat Rate Envelope 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. label_messages: allOf: - $ref: '#/components/schemas/label_messages' external_package_id: type: string minLength: 1 description: An external package id. example: se-1234545 tracking_number: readOnly: true allOf: - $ref: '#/components/schemas/tracking_number' description: > The tracking number for the package. The format depends on the carrier. 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 x-nullable: true products: type: array default: [] minItems: 0 description: >- Details about products inside packages (Information provided would be used on custom documentation) items: title: products type: object description: The customs declaration for a single item in the shipment. additionalProperties: false properties: description: type: string x-nullable: true maxLength: 100 default: null description: A description of the item example: a minimum description quantity: type: integer format: int32 minimum: 0 default: 0 description: The quantity of this item in the shipment. example: 1 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 x-nullable: true default: null example: '3926.10' description: >- The [Harmonized Tariff Code](https://en.wikipedia.org/wiki/Harmonized_System) of this item. country_of_origin: x-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 x-nullable: true example: pound sku: type: string description: The SKU (Stock Keeping Unit) of the item x-nullable: true example: sku-1223344 sku_description: type: string description: Description of the Custom Item's SKU x-nullable: true example: this is a description mid_code: type: string description: Manufacturers Identification code x-nullable: true example: GBCOM15BRI product_url: type: string description: link to the item on the seller website x-nullable: true example: https://myproduct.com vat_rate: type: number description: VAT rate applicable to the item x-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' 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 x-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. example: Reference reference2: type: string x-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. example: Reference 2 reference3: type: string x-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. example: Reference 3 weight: title: weight type: object description: The weight of a package required: - value - unit additionalProperties: false properties: value: type: number minimum: 0 exclusiveMinimum: 1 example: 23 description: The weight, in the specified unit unit: allOf: - $ref: '#/components/schemas/weight_unit' description: Weight unit dangerous_goods: title: dangerous_goods type: object description: | Dangerous goods attribute associated with the product additionalProperties: false properties: id_number: type: string x-nullable: true default: null description: UN number to identify the dangerous goods. example: 1234r1 shipping_name: type: string x-nullable: true default: null description: Trade description of the dangerous goods. example: things with dangerous goods technical_name: type: string x-nullable: true default: null description: Recognized Technical or chemical name of dangerous goods. example: chloric acid product_class: type: string x-nullable: true default: null description: Dangerous goods product class based on regulation. example: '1987' product_class_subsidiary: type: string x-nullable: true default: null description: >- A secondary of product class for substances presenting more than one particular hazard example: '1987' packaging_group: title: packaging_group type: string enum: - i - ii - iii example: ii 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. example: 1 packaging_instruction: type: string x-nullable: true default: null description: >- The specific standardized packaging instructions from the relevant regulatory agency that have been applied to the parcel/container. example: >- Packaging materials and containers that are in contact with food products must comply with the provisions established by Regulation packaging_instruction_section: title: packaging_instruction_section type: string enum: - section_1 - section_2 - section_1a - section_1b example: section_1 packaging_type: type: string x-nullable: true default: null description: The type of exterior packaging used to contain the dangerous good. example: X transport_mean: title: transport_mean type: string enum: - ground - water - cargo_aircraft_only - passenger_aircraft example: ground transport_category: type: string x-nullable: true default: null description: >- Transport category assign to dangerous goods for the transport purpose. example: '6.1' regulation_authority: type: string x-nullable: true default: null description: Name of the regulatory authority. example: AEAT regulation_level: title: regulation_level type: string enum: - lightly_regulated - fully_regulated - limited_quantities - excepted_quantity example: excepted_quantity radioactive: type: boolean x-nullable: true example: false description: Indication if the substance is radioactive. reportable_quantity: type: boolean x-nullable: true example: false description: >- Indication if the substance needs to be reported to regulatory authority based on the quantity. tunnel_code: type: string x-nullable: true default: null description: Defines which types of tunnels the shipment is allowed to go through example: all additional_description: type: string x-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 example: any description dangerous_amount: title: dangerous_amount type: object description: This model represents the amount of the dangerous goods.. additionalProperties: false properties: amount: type: number minimum: 0 default: 0 description: The amount of dangerous goods. example: 12 unit: type: string x-nullable: true default: null description: The unit of dangerous goods. example: GBP 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 x-nullable: true default: null description: | The instructions for the paperless download. example: any instructions handoff_code: type: string x-nullable: true default: null example: '122334' description: | The handoff code for the paperless download. 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 advanced_shipment_options: title: advanced_shipment_options type: object description: Advanced shipment options additionalProperties: false properties: bill_to_account: type: string x-nullable: true default: null description: > This field is used to [bill shipping costs to a third party]. This field must be used in conjunction with the `bill_to_country_code`, `bill_to_party`, and `bill_to_postal_code` fields. example: '123456789' bill_to_country_code: x-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. example: US bill_to_party: x-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. example: third_party bill_to_postal_code: type: string x-nullable: true default: null description: > The postal code of the third-party that is responsible for shipping costs. example: '28005' contains_alcohol: type: boolean default: false description: Indicates that the shipment contains alcohol. example: true 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. example: true dry_ice: type: boolean default: false description: Indicates if the shipment contain dry ice example: true dry_ice_weight: x-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. example: true saturday_delivery: type: boolean default: false description: Enables Saturday delivery, if supported by the carrier. example: true fedex_freight: type: object description: Provide details for the Fedex freight service properties: shipper_load_and_count: type: string example: shipper_load_and_count booking_confirmation: type: string example: today use_ups_ground_freight_pricing: type: boolean x-nullable: true default: null description: > Whether to use [UPS Ground Freight pricing] If enabled, then a `freight_class` must also be specified. example: true freight_class: type: string x-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 x-nullable: true default: null maxLength: 100 description: > An arbitrary field that can be used to store information about the shipment. example: custom field 1 custom_field2: type: string x-nullable: true default: null maxLength: 100 description: > An arbitrary field that can be used to store information about the shipment. example: custom field 2 custom_field3: type: string x-nullable: true default: null maxLength: 100 description: > An arbitrary field that can be used to store information about the shipment. example: custom field 3 origin_type: x-nullable: true default: null allOf: - $ref: '#/components/schemas/origin_type' additional_handling: type: boolean x-nullable: true default: null description: > Indicate to the carrier that this shipment requires additional handling. example: true shipper_release: type: boolean x-nullable: true default: null example: true 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: title: payment_amount type: object properties: currency: allOf: - $ref: '#/components/schemas/currency' example: USD amount: minimum: 0 type: number example: 12 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 example: true dangerous_goods: type: boolean default: false description: Indicates if the Dangerous goods are present in the shipment example: true dangerous_goods_contact: type: object description: Contact information for Dangerous goods properties: name: type: string description: Name of the contact example: Michael Robinson phone: type: string description: Phone number of the contact example: '123456578789' windsor_framework_details: type: object description: >- The Windsor framework is a new regulation in the UK that simplifies customs procedures for goods moved from the UK mainland to Northern Ireland. properties: movement_indicator: type: string description: >- An indicator that will tell the carrier and HMRC the type of movement for the shipment. enum: - c2c - b2c - c2b - b2b example: b2b not_at_risk: type: boolean description: >- An indicator that allows a shipper to declare the shipment as not-at-risk. example: true ancillary_endorsements_option: type: string x-nullable: true description: Ancillary endorsements option for the shipment example: forward return_pickup_attempts: type: integer x-nullable: true description: Number of return pickup attempts example: 3 own_document_upload: type: boolean default: false description: Indicates if own document upload is enabled example: false limited_quantity: type: boolean default: false description: Indicates if the shipment contains limited quantities example: false event_notification: type: boolean default: false description: Indicates if event notifications are enabled example: false 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`) example: rubber duckies 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/terms_of_trade_code' declaration: type: string description: Declaration statement to be placed on the commercial invoice example: >- I hereby certify that the information on this invoice is true and correct and that the contents and value of this shipment are as stated above 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: 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 x-nullable: true maxLength: 100 default: null description: A description of the item example: This is a description quantity: type: integer format: int32 minimum: 0 default: 0 description: The quantity of this item in the shipment. example: 1 value: type: number minimum: 0 description: The monetary amount, in the specified currency. example: 12 value_currency: type: string description: > The currencies that are supported by ShipStation are the ones that specified by ISO 4217: https://www.iso.org/iso-4217-currency-codes.html example: USD weight: allOf: - $ref: '#/components/schemas/weight' description: The item weight harmonized_tariff_code: type: string x-nullable: true default: null example: '3926.10' description: >- The [Harmonized Tariff Code](https://en.wikipedia.org/wiki/Harmonized_System) of this item. country_of_origin: x-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 example: GB unit_of_measure: type: string x-nullable: true example: pound sku: type: string description: The SKU (Stock Keeping Unit) of the customs item x-nullable: true example: sku-1234 sku_description: type: string description: Description of the Custom Item's SKU x-nullable: true example: this is a description 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 x-nullable: true example: example@example.com description: | Email for the address owner. company_name: type: string minLength: 1 x-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 x-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 x-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) 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. estimated_import_charges: allOf: - $ref: '#/components/schemas/estimated_import_charges' description: >- Estimated import charges for commercial invoices for international shipments. 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). example: Other charges description 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 x-nullable: true description: | Additional text about how to handle the shipment at this address. example: any instruction 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 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. example: US value: type: string description: The value of the identifier example: value shipment_item: title: shipment_item type: object description: A shipment item additionalProperties: false properties: name: type: string minLength: 0 description: item name example: box sales_order_id: type: string x-nullable: true description: sales order id example: '12345' sales_order_item_id: type: string x-nullable: true description: sales order item id example: '1234556' quantity: type: integer format: int32 minimum: 0 description: The quantity of this item included in the shipment example: 1 sku: type: string x-nullable: true description: Item Stock Keeping Unit example: sku-1234 bundle_sku: type: string x-nullable: true description: Bundle SKU for the item example: bundle-123 external_order_id: type: string x-nullable: true description: external order id example: '123445' external_order_item_id: type: string x-nullable: true description: external order item id example: '12' asin: type: string x-nullable: true minLength: 10 maxLength: 10 example: B00005N5PF description: Amazon Standard Identification Number order_source_code: allOf: - $ref: '#/components/schemas/order_source_name' item_id: type: string x-nullable: true description: Unique identifier for the item example: '1402291169813' allocation_status: type: string x-nullable: true description: Allocation status of the item example: allocated image_url: type: string x-nullable: true format: uri description: URL to the item image example: https://example.com/image.jpg weight: allOf: - $ref: '#/components/schemas/weight' description: Weight of the individual item unit_price: type: number x-nullable: true minimum: 0 description: Unit price of the item example: 88 tax_amount: type: number x-nullable: true minimum: 0 description: Tax amount for the item example: 5.5 shipping_amount: type: number x-nullable: true minimum: 0 description: Shipping amount for the item example: 10 inventory_location: type: string x-nullable: true description: Inventory location of the item example: warehouse-a options: type: array default: [] items: type: object properties: name: type: string description: Option name example: Color value: type: string description: Option value example: Red description: Item options/variants product_id: type: string x-nullable: true description: Product ID example: '10408926' fullfilment_sku: type: string x-nullable: true description: Fulfillment SKU example: fulfill-123 upc: type: string x-nullable: true description: Universal Product Code example: '123456789012' 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 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. example: se-8412 carrier_code: readOnly: true allOf: - $ref: '#/components/schemas/carrier_code' description: > The [shipping carrier] 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 example: true balance: type: number readOnly: true example: 3799.52 minimum: 0 description: Current available balance nickname: type: string readOnly: true minLength: 1 example: ShipStation 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 funding_source_id: readOnly: true x-nullable: true allOf: - $ref: '#/components/schemas/se_id' description: Funding source ID for the carrier primary: type: boolean readOnly: true example: 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 example: true description: Carrier supports multiple packages per shipment supports_label_messages: type: boolean readOnly: true example: true description: The carrier supports adding custom label messages to an order. disabled_by_billing_plan: type: boolean readOnly: true example: true description: >- The carrier is disabled by the current ShipStation 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 send_rates: type: boolean readOnly: true description: The carrier provides rates for the shipment. example: true supports_user_managed_rates: type: boolean readOnly: true description: The carrier supports user-managed rates for shipments. example: true 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 example: The description description: Description of option 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 ShipStation 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. 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/tracking_status_detail_code' readOnly: true example: COLLECTION_FAILED status_detail_code: allOf: - $ref: '#/components/schemas/tracking_status_detail_code' readOnly: true example: DELIVERED carrier_code: allOf: - $ref: '#/components/schemas/carrier_code' readOnly: true carrier_id: readOnly: true type: integer format: int32 description: > The unique ID of the [carrier account] that was used to create this label example: 1234567 status_description: type: string readOnly: true example: Delivered minLength: 0 description: Status description status_detail_description: type: string readOnly: true example: Your shipment has been delivered. minLength: 0 description: Status detail 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' example: '2024-12-23T00:00:00.000Z' 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 example: this is exception description events: type: array readOnly: true items: 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' example: DE company_name: type: string readOnly: true example: Stamps.com minLength: 0 description: Company Name signer: type: string minLength: 0 readOnly: true description: Signer information example: '' event_code: type: string minLength: 0 description: Event Code example: DLD carrier_detail_code: type: string readOnly: true minLength: 1 example: OT description: Carrier detail code status_code: allOf: - $ref: '#/components/schemas/tracking_status_detail_code' readOnly: true example: COLLECTION_FAILED status_detail_code: allOf: - $ref: '#/components/schemas/tracking_status_detail_code' readOnly: true example: IN_TRANSIT status_description: type: string readOnly: true minLength: 1 example: In Transit description: Event Status Description status_detail_description: type: string readOnly: true minLength: 0 example: Your shipment is on its way between depots. description: Event Status Detail Description carrier_status_code: type: string readOnly: true minLength: 1 example: '01' 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. example: 89 longitude: type: number format: double minimum: -180 maximum: 180 description: Longitude coordinate of tracking event. example: 23 proof_of_delivery_url: type: string readOnly: true example: >- https://tracking-service-prod.s3.amazonaws.com/proof-of-delivery/dummy_module/0000000001/bc6dd17969bd97f24262ca73ac6ff36062aafecba25ef16d4178264bf7c0e72c.png description: >- A URL to an image captured at the time of delivery, serving as evidence that the shipment was successfully delivered to the recipient. It can be used to capture things like recipient's signature, location of delivery, condition of the package upon delivery, etc. description: >- The events that have occured during the lifetime of this tracking number. 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 schedule_pickup_response_body: title: schedule_pickup_response_body type: object description: A schedule pickup response body required: - 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' 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.05Z' 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.05Z' 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 example: se-1234567 manifest_download: readOnly: true allOf: - $ref: '#/components/schemas/manifest_download' 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' manifest_requests: 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' 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.05Z' 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.05Z' 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 example: se-1234567 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: 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 label_id: allOf: - $ref: '#/components/schemas/se_id' readOnly: true description: >- The label this error is associated with if it is specific to a individual label. 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_with_label_id' description: The errors associated with the failed API call 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/manifest_requests' - $ref: '#/components/schemas/deprecated_manifest' - $ref: '#/components/schemas/error_with_label_id_response_body' 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 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' create_webhook_response_body: title: create_webhook_response_body type: object description: A webhook response body additionalProperties: false required: - webhook_id - url - event - name allOf: - $ref: '#/components/schemas/webhook' 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 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' 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 create_tag_response_body: title: create_tag_response_body type: object description: Response body for creating tags additionalProperties: false allOf: - $ref: '#/components/schemas/tag' 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 tag_shipment_response_body: title: tag_shipment_response_body type: object description: A shipment add tag response body required: - shipment_id - tag additionalProperties: false properties: shipment_id: readOnly: true allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the shipment tag: readOnly: true allOf: - $ref: '#/components/schemas/tag' description: The tag that is now associated with this 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' 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' 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' 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: 12 pages: type: integer format: int32 readOnly: true minimum: 1 example: 4 links: readOnly: true allOf: - $ref: '#/components/schemas/pagination_link' 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' estimate_rates_response_body: title: estimate_rates_response_body type: array description: A rate estimate response body items: allOf: - $ref: '#/components/schemas/rate-estimate' 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' - title: rate_response type: object additionalProperties: false properties: rate_response: allOf: - $ref: '#/components/schemas/rates_information' description: The rates response 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' 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' 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 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' 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' 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 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' 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/label_void_failure_reason' 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 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' 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' 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_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_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 - rate_details allOf: - $ref: '#/components/schemas/label' 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: $ref: '#/components/schemas/label' allOf: - $ref: '#/components/schemas/paged_list_response_body' 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 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 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' 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 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: 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 example: '1234567' description: An external shipment id associated with the shipment description: The errors currently associated with the batch links: readOnly: true allOf: - $ref: '#/components/schemas/pagination_link' 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' 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 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' ListBatchesResponseBody: 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' CreateBatchResponseBody: title: create_batch_response_body type: object description: A create batch response body additionalProperties: false allOf: - $ref: '#/components/schemas/batch' 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 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` manifest_request_status: title: manifest_request_status type: string enum: - in_progress - completed description: The possible statuses of a manifest request validation_status: title: validation_status type: string enum: - valid - invalid - has_warnings - unknown description: The possible validation status values tracking_status_detail_code: title: status_detail_code enum: - COLLECTION_FAILED - AWAITING_DESPATCH - COLLECTION_REQUESTED - DESPATCHED - ELEC_ADVICE_RECD_BY_CARRIER - NOT_YET_RECEIVED_BY_CARRIER - COLLECTION_MADE - ATTEMPTED_DELIVERY - ATTEMPTED_DELIVERY_2ND - ATTEMPTED_DELIVERY_3RD - COD_AMOUNT_NOT_PAID - COD_AMOUNT_PAID - CUSTOMER_CARDED - CUSTOMER_IDENTIFICATION_FAILED - INVALID_METHOD_OF_PAYMENT - NO_ACCESS_TO_RECIPIENTS_ADDRESS - OUT_FOR_DELIVERY - DELIVERED - DELIVERED_DAMAGED - DELIVERED_IN_PART - DELIVERED_SPECIFIED_SAFE_PLACE - DELIVERED_TO_ALTERNATIVE_DELIVERY_LOCATION - DELIVERED_TO_NEIGHBOUR - DELIVERED_TO_PO_BOX - PARCEL_COLLECTED_FROM_PICKUP_POINT - POST_TRANSIT_STATUS - PROOF_OF_DELIVERY - CANCELLED - CANCELLED_BEFORE_DESPATCH - CUSTOMER_MOVED - HAZARDOUS_PROHIBITED - NOT_COLLECTED_FROM_PICKUP_POINT - NOT_DELIVERED - NOT_DELIVERED_ADDRESSEE_DECEASED - PARCEL_DAMAGED - PARCEL_DISPOSED - PARCEL_LOST - PARCEL_OUTSIDE_OF_SERVICE_CAPABILITY - REFUSED_BY_CUSTOMER - RETURN_TO_SENDER - ADDRESS_QUERY - CARRIER_DELAYS - CUSTOMS_CLEARED - CUSTOMS_PROCESSING - DELAYED_NOT_CARRIER - DELIVERY_ARRANGED_WITH_RECIPIENT - HELD_BY_CARRIER - HELD_BY_CARRIER_FOR_CLEARANCE_PRE_PROCESSING - HELD_BY_CUSTOMS - HELD_BY_EXPORT_CUSTOMS - HELD_BY_IMPORT_CUSTOMS - HUB_SCAN_OUT - IN_TRANSIT - INCORRECT_DECLARATION - INFORMATION - MISSORTED - PARCEL_OVER_LABELLED - PARCEL_REPACKED - PARCEL_UPDATE_NOTIFICATION_VIA_EMAIL - PARCEL_UPDATE_NOTIFICATION_VIA_SMS - RECEIVED_BY_CARRIER - RECEIVED_LOCAL_DELIVERY_DEPOT - ROUTING_ERROR - SUB_CONTRACTOR_EVENT - SUB_CONTRACTOR_RECEIVED - RECD_BY_CARRIER_NO_ELEC_ADVICE - AWAITING_ELECTRONIC_ADVICE - AWAITING_COLLECTION_FROM_PICKUP_POINT - COLLECT_AT_LOCAL_PO - CUSTOMER_TO_COLLECT_FROM_CARRIER - DELIVERED_TO_LOCKER_COLLECTION_POINT - CARRIER_STATUS_NOT_MAPPED type: string description: > The tracking status detail codes |Value |Description |:--------- |:----------------------------------------------------- | `COLLECTION_FAILED` | Shipment pickup failed. The delivery company will try again soon. | `AWAITING_DESPATCH` | Your shipment is ready to go and is waiting for pickup. | `COLLECTION_REQUESTED` | Your shipment pickup has been scheduled. | `DESPATCHED` | Your shipment has been handed over to the carrier or dropped off at collection point. It will soon start its journey. | `ELEC_ADVICE_RECD_BY_CARRIER` | Your shipment is now in the carrier's system. | `NOT_YET_RECEIVED_BY_CARRIER` | The sender couldn't hand over your shipment. The delivery company will try to collect it again. | `COLLECTION_MADE` | Your shipment has been picked up by the carrier. | `ATTEMPTED_DELIVERY` | Delivery attempt failed. Please check the carrier's instructions for next steps. | `ATTEMPTED_DELIVERY_2ND` | Second delivery attempt failed. Please check the carrier's instructions for next steps. | `ATTEMPTED_DELIVERY_3RD` | Third delivery attempt failed. Please check the carrier's instructions for next steps. | `COD_AMOUNT_NOT_PAID` | Delivery failed due to unpaid cash on delivery. Please check carrier instructions. | `COD_AMOUNT_PAID` | Cash on delivery payment received. | `CUSTOMER_CARDED` | Delivery attempt failed. Please check for delivery instructions left by the carrier. | `CUSTOMER_IDENTIFICATION_FAILED` | There was a recipient identification issue. Please check carrier instructions. | `INVALID_METHOD_OF_PAYMENT` | Delivery failed due to incorrect payment. Please check carrier instructions. | `NO_ACCESS_TO_RECIPIENTS_ADDRESS` | Delivery couldn't be completed due to issues with accessing address. Please follow carrier instructions. | `OUT_FOR_DELIVERY` | Your shipment is out for delivery. | `DELIVERED` | Your shipment has been delivered. | `DELIVERED_DAMAGED` | Your shipment was delivered but arrived damaged. | `DELIVERED_IN_PART` | Part of your shipment has been delivered. Check for updates on the rest. | `DELIVERED_SPECIFIED_SAFE_PLACE` | Your shipment has been left in your designated safe place. | `DELIVERED_TO_ALTERNATIVE_DELIVERY_LOCATION` | Your shipment was delivered to an alternative location due to the delivery company being unable to deliver it to the specified address. Check carrier instructions for pickup details. | `DELIVERED_TO_NEIGHBOUR` | Your shipment was delivered to your neighbor. | `DELIVERED_TO_PO_BOX` | Your shipment was delivered to your PO Box. | `PARCEL_COLLECTED_FROM_PICKUP_POINT` | Your package has been picked up from the collection point. | `POST_TRANSIT_STATUS` | The carrier has added more information about your delivery. | `PROOF_OF_DELIVERY` | Delivery confirmed. | `CANCELLED` | Your shipment has been cancelled. | `CANCELLED_BEFORE_DESPATCH` | Your shipment was cancelled before pickup. Contact the sender if unexpected. | `CUSTOMER_MOVED` | Recipient not at address. Your shipment is being returned. | `HAZARDOUS_PROHIBITED` | Your parcel contained a prohibited item and is being returned. Contact the sender. | `NOT_COLLECTED_FROM_PICKUP_POINT` | Shipment not collected from the pickup point. Your parcel is being returned to the sender. | `NOT_DELIVERED` | Delivery attempts failed. Your parcel is being returned to the sender. | `NOT_DELIVERED_ADDRESSEE_DECEASED` | Delivery not possible due to recipient's passing. | `PARCEL_DAMAGED` | Your parcel was damaged and can't be delivered. It's being returned. Contact the sender. | `PARCEL_DISPOSED` | Shipment was disposed of. Contact the sender for details. | `PARCEL_LOST` | Your parcel is lost. Contact the sender for next steps. | `PARCEL_OUTSIDE_OF_SERVICE_CAPABILITY` | Shipment is too large/heavy for delivery. Being returned. Contact sender. | `REFUSED_BY_CUSTOMER` | Delivery refused. Shipment being returned. Contact the sender. | `RETURN_TO_SENDER` | Your shipment is being returned to the sender. Contact them for details. | `ADDRESS_QUERY` | There's an issue with your delivery address. This may cause a delay or return. Contact sender or carrier. | `CARRIER_DELAYS` | There's a delivery delay. We'll update you when there's more info. | `CUSTOMS_CLEARED` | Your shipment has passed customs clearance. | `CUSTOMS_PROCESSING` | Your shipment is going through customs. | `DELAYED_NOT_CARRIER` | Unexpected delivery delay. We'll update you soon. | `DELIVERY_ARRANGED_WITH_RECIPIENT` | Delivery arranged by recipient. | `HELD_BY_CARRIER` | Your shipment is on hold due to a carrier issue. We'll update you soon. | `HELD_BY_CARRIER_FOR_CLEARANCE_PRE_PROCESSING` | Your shipment is held by carrier due to customs issues. We'll update you. | `HELD_BY_CUSTOMS` | Your shipment is held in customs. We'll update you. | `HELD_BY_EXPORT_CUSTOMS` | Your shipment is held in export customs. We'll update you. | `HELD_BY_IMPORT_CUSTOMS` | Your shipment is held in import customs. We'll update you. | `HUB_SCAN_OUT` | Your shipment is at the main delivery depot. | `IN_TRANSIT` | Your shipment is on its way between depots. | `INCORRECT_DECLARATION` | Incorrect shipment dimensions. Delivery may be delayed or returned. We'll update you. | `INFORMATION` | The carrier has shared additional shipment information. | `MISSORTED` | Your shipment was missorted. There might be a delivery delay. We'll update you. | `PARCEL_OVER_LABELLED` | Your shipment was over labelled by the delivery company to improve processing. | `PARCEL_REPACKED` | Your shipment packaging was damaged. It's being repacked. This might delay delivery. | `PARCEL_UPDATE_NOTIFICATION_VIA_EMAIL` | You've received an email with a shipment update. | `PARCEL_UPDATE_NOTIFICATION_VIA_SMS` | You've received a text message with a shipment update. | `RECEIVED_BY_CARRIER` | Your shipment has been received by the carrier. | `RECEIVED_LOCAL_DELIVERY_DEPOT` | Your shipment is at the local delivery depot, ready for delivery. | `ROUTING_ERROR` | Your shipment was sent to the wrong place. There might be a delay. | `SUB_CONTRACTOR_EVENT` | Your shipment is with the local delivery partner. | `SUB_CONTRACTOR_RECEIVED` | Your shipment has been received by the local delivery partner. | `RECD_BY_CARRIER_NO_ELEC_ADVICE` | There's a system issue with your shipment. Tracking updates might be delayed. | `AWAITING_ELECTRONIC_ADVICE` | Your tracking number is ready. Your shipment is waiting to be registered in the carrier system and scheduled for pickup. | `AWAITING_COLLECTION_FROM_PICKUP_POINT` | Your shipment is ready for pickup at the specified location. | `COLLECT_AT_LOCAL_PO` | Your shipment has been redirected to the local post office for pickup. Check carrier instructions. | `CUSTOMER_TO_COLLECT_FROM_CARRIER` | Your shipment is being held for pickup. Check carrier instructions. | `DELIVERED_TO_LOCKER_COLLECTION_POINT` | Your shipment has been delivered to your locker. | `CARRIER_STATUS_NOT_MAPPED` | Status not mapped. Please check the carrier's website for updates. identifier_type: title: identifier_type type: string enum: - vat - eori - ssn - ein - tin - ioss - pan - voec - pccc - oss - passport - abn - ukims 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. |`ukims` | The tax identifier is an UK Internal Market Scheme number. 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. 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 terms_of_trade_code: title: Allowed incoterms type: string enum: - exw - fca - cpt - cip - dpu - dap - ddp - fas - fob - cfr - cif - ddu - daf - deq - des 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_payment_type: title: collect_on_delivery_payment_type type: string enum: - any - cash - cash_equivalent - none description: Types of payment that are supported 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 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_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_status: title: address_validation_status type: string enum: - unverified - verified - warning - error description: The possible address validation status values 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 error_type: title: error_type type: string enum: - account_status - business_rules - validation - security - system - integrations description: | The type of error error_source: title: error_source type: string enum: - carrier - order_source - ShipStation 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 ShipStation API itself. weight_unit: title: weight_unit type: string enum: - pound - ounce - gram - kilogram description: The possible weight unit values dimension_unit: title: dimension_unit type: string enum: - inch - centimeter description: The dimension units that are supported by ShipStation . rate_response_status: title: rate_response_status type: string enum: - working - completed - partial - error description: The possible rate response status values rate_type: title: rate_type type: string enum: - check - shipment description: The possible rate type values insurance_provider: title: insurance_provider type: string enum: - none - shipsurance - carrier - third_party description: The possible insurance provider values currency: title: currency type: string description: > The currencies that are supported by ShipStation are the ones that specified by ISO 4217: https://www.iso.org/iso-4217-currency-codes.html tracking_status: title: tracking_status type: string enum: - unknown - in_transit - error - delivered description: The different statuses that can apply to a shipment. label_void_failure_reason: 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 validate_address: title: validate_address type: string enum: - no_validation - validate_only - validate_and_clean description: The possible validate address values 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. 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_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. address_residential_indicator: title: address_residential_indicator type: string enum: - unknown - 'yes' - 'no' description: Indicates whether an address is residential. 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 webhook_event: title: webhook_event type: string enum: - batch - carrier_connected - order_source_refresh_complete - rate - report_complete - sales_orders_imported - track - batch_processed_v2 - fulfillment_rejected_v2 - fulfillment_shipped_v2 - label_created_v2 - shipment_created_v2 - track_event_v2 description: The possible webhook event values batches_sort_by: title: batches_sort_by type: string enum: - ship_date - processed_at - created_at description: The possible batches sort by values label_status: title: label_status type: string enum: - processing - completed - error - voided description: > The possible statuses that a [shipping label] can be in. |Status |Description |:------------|:----------------------------------------------------- |`processing` |When labels are created in a [batch], 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] shipment_status: title: shipment_status type: string enum: - pending - processing - label_purchased - cancelled description: The possible shipment status values shipments_sort_by: title: shipments_sort_by type: string enum: - modified_at - created_at description: The possible shipments sort by values batch_status: title: batch_status type: string enum: - open - queued - processing - completed - completed_with_errors - archived - notifying - invalid description: The possible batch status values label_download_type: title: label_download_type type: string enum: - url - inline description: > There are two different ways to [download a label]: |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. 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 ShipStation 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 tracking_number: title: tracking_number type: string minLength: 1 example: 1Z932R800392060079 description: A tracking number for a package. The format depends on the carrier. email: title: email type: string format: email minLength: 1 example: john.doe@example.com description: An email address. carrier_code: title: carrier_code type: string pattern: ^[a-z0-9]+(_[a-z0-9]+)*$ example: dhl_express description: > A [shipping carrier] , such as `fedex`, `dhl_express`, `stamps_com`, etc. 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] , such as `thick_envelope`, `small_flat_rate_box`, `large_package`, etc. Use the code `package` for custom or unknown package types. 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-23' 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 ShipStation . 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) 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. url: title: url type: string format: url minLength: 1 example: http://api.shipstation.com/v2/labels/se-28529731 description: A URL pickup_resource_id: title: pickup_resource_id type: string minLength: 4 example: pik_3YcKU5zdtJuCqoeNwyqqbW description: Pickup Resource ID image_id: title: image_id type: string minLength: 4 example: img_DtBXupDBxREpHnwEXhTfgK description: Used to identify an image resource. 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. 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 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 ShipStation resource, such as a carrier, label, shipment, etc. service_code: title: service_code type: string pattern: ^[a-z0-9]+(_[a-z0-9-]+)* ?$ example: usps_first_class_mail description: > A [carrier service], such as `fedex_ground`, `usps_first_class_mail`, `flat_rate_envelope`, etc. update_webhook_request_body: title: update_webhook_request_body type: object description: An update webhook request body additionalProperties: false properties: name: type: string description: The name of the webhook example: My Updated Webhook 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 create_webhook_request_body: title: create_webhook_request_body type: object description: A create webhook request body required: - event - url - name additionalProperties: false properties: name: type: string description: The name of the webhook example: My New Webhook 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 store_id: type: integer description: Store ID example: 123456 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: - 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 example: se-1234567 - 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 allOf: - 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/weigth' 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 calculate_rates_request_body: title: calculate_rates_request_body type: object description: A rate shipment request body required: - shipment_id - shipment additionalProperties: false oneOf: - title: shipment_id_request type: object properties: shipment_id: allOf: - $ref: '#/components/schemas/se_id' description: A string that uniquely identifies the shipment - title: shipment_request type: object properties: shipment: allOf: - $ref: '#/components/schemas/address_validating_shipment' description: The shipment object allOf: - title: rate_request_options type: object properties: rate_options: allOf: - $ref: '#/components/schemas/rate_request_body' description: The rate options 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' 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' 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_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: x-nullable: true allOf: - $ref: '#/components/schemas/image_id' description: >- The label image resource that was used to create a custom label image. 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. 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_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' 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: x-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: x-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' 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. 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 example: se-123456 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 example: true 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. 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' 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_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 example: se-1234567 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 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. example: true preferred_currency: allOf: - $ref: '#/components/schemas/currency' is_return: type: boolean description: Indicate if it's a return shipment example: true 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' 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/create_shipment_request' description: Array of shipments to create create_shipment_request: title: create_shipment_request type: object description: A single shipment creation request additionalProperties: false properties: validate_address: allOf: - $ref: '#/components/schemas/validate_address' description: Address validation option external_shipment_id: type: string maxLength: 50 x-nullable: true example: '1751939189' description: > A unique user-defined key to identify a shipment. This can be used to retrieve the shipment. carrier_id: x-nullable: true allOf: - $ref: '#/components/schemas/se_id' description: The carrier account that is billed for the shipping charges example: se-2774150 create_sales_order: type: boolean default: false description: Whether to create a sales order for this shipment example: true store_id: x-nullable: true type: string description: The store ID associated with the shipment example: '1582173' notes_from_buyer: type: string x-nullable: true description: Notes from the buyer example: I am a note from the buyer notes_for_gift: type: string x-nullable: true description: Gift notes example: I am a gift note is_gift: type: boolean default: false description: Indicates if the shipment is a gift example: true zone: type: integer format: int32 x-nullable: true minimum: 0 description: Shipping zone example: 0 display_scheme: type: string x-nullable: true description: Display scheme for the shipment example: paperless assigned_user: type: string x-nullable: true description: User assigned to the shipment example: a2df9fa5-b7ee-467f-be4e-9c660542c187 shipment_status: allOf: - $ref: '#/components/schemas/shipment_status' description: The status of the shipment example: pending amount_paid: allOf: - $ref: '#/components/schemas/monetary_value' description: Total amount paid for the order shipping_paid: allOf: - $ref: '#/components/schemas/monetary_value' description: Amount paid for shipping tax_paid: allOf: - $ref: '#/components/schemas/monetary_value' description: Amount paid for taxes 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 items: type: array default: [] items: allOf: - $ref: '#/components/schemas/shipment_item' description: Items included in this shipment packages: type: array minItems: 1 items: allOf: - $ref: '#/components/schemas/package' description: The packages in the shipment 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 readOnly: true description: Indicates if any shipments had errors during creation example: false shipments: type: array readOnly: true items: allOf: - $ref: '#/components/schemas/create_shipment_response' description: Array of created shipments with their results create_shipment_response: title: create_shipment_response type: object description: A single shipment creation response additionalProperties: false allOf: - $ref: '#/components/schemas/shipment' - title: create_shipment_response_fields type: object properties: errors: type: array readOnly: true items: type: string minLength: 1 example: Parameter value is out of range. description: An error that occurred while creating the shipment. description: An array of errors that occurred while creating the shipment. address_validation: x-nullable: true allOf: - $ref: '#/components/schemas/address_validation_result' description: The address validation result 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 responses: ServerError: description: The request was successful. content: text/plain: schema: title: empty_response_body type: string maxLength: 0 application/json: schema: title: empty_response_body type: string maxLength: 0 NotFound: description: The specified resource does not exist. content: application/json: schema: $ref: '#/components/schemas/error_response_body' BadRequest: description: The request contained errors. content: application/json: schema: $ref: '#/components/schemas/error_response_body' NoContent: description: The request was successful. content: text/plain: schema: title: empty_response_body type: string maxLength: 0 application/json: schema: title: empty_response_body type: string maxLength: 0 conflict: description: The request conflicts with an existing resource. content: application/json: schema: $ref: '#/components/schemas/error_response_body' parameters: batch_id_path_param: name: batch_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Batch ID batch_id_query_param: name: batch_id in: query required: false schema: $ref: '#/components/schemas/se_id' description: Batch ID batch_number_query_param: name: batch_number in: query required: false schema: type: string description: Batch Number batch_status_query_param: name: status in: query required: false schema: $ref: '#/components/schemas/batch_status' carrier_code_query_param: name: carrier_code in: query required: false schema: type: string minLength: 1 example: stamps_com description: > A [shipping carrier] , such as `fedex`, `dhl_express`, `stamps_com`, etc. carrier_id_path_param: name: carrier_id in: path required: true schema: $ref: '#/components/schemas/se_id' example: se-28529731 description: Carrier ID carrier_id_query_param: name: carrier_id in: query required: false schema: $ref: '#/components/schemas/se_id' description: Carrier ID created_at_end_query_param: 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) created_at_start_query_param: 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) dir_path_param: name: dir in: path required: true schema: type: string external_batch_id_path_param: name: external_batch_id in: path required: true schema: type: string example: 13553d7f-3c87-4771-bae1-c49bacef11cb external_shipment_id_path_param: name: external_shipment_id in: path schema: type: string required: true example: 0bcb569d-1727-4ff9-ab49-b2fec0cee5ae external_shipment_id_query_param: name: external_shipment_id in: query schema: type: string required: false example: 0bcb569d-1727-4ff9-ab49-b2fec0cee5ae filename_path_param: name: filename in: path required: true schema: type: string item_keyword_query_param: name: item_keyword in: query schema: type: string required: false example: coat description: >- Returns shipments that contain items that match the specified keyword. Fields searched are Sku, Description, and Options. label_download_type_query_param: name: label_download_type in: query required: false schema: $ref: '#/components/schemas/label_download_type' example: url label_id_path_param: name: label_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Label ID label_ids_query_param: name: label_ids in: query explode: true required: false schema: type: array items: $ref: '#/components/schemas/se_id' description: Array of label ids manifest_id_path_param: name: manifest_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: The Manifest Id subdir_path_param: name: subdir in: path required: true schema: type: string modified_at_end_query_param: name: modified_at_end in: query required: false schema: type: string format: date-time example: '2025-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) modified_at_start_query_param: name: modified_at_start in: query required: false schema: type: string format: date-time example: '2025-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) package_id_path_param: name: package_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Package ID page_query_param: 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. page_size_query_param: 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. pagesize_query_param: name: pagesize in: query required: false schema: type: integer format: int32 minimum: 1 payment_date_start_query_param: name: payment_date_start in: query required: false schema: type: string format: date-time example: '2025-03-12T19:24:13.657Z' description: >- Used to create a filter for resources based on the payment_date parameter after a certain time. payment_date_end_query_param: name: payment_date_end in: query required: false schema: type: string format: date-time example: '2025-03-12T19:24:13.657Z' description: >- Used to create a filter for resources based on the payment_date parameter before a certain time. pickup_id_query_param: name: pickup_id in: query required: true schema: $ref: '#/components/schemas/pickup_resource_id' pickup_id_path_param: name: pickup_id in: path required: true schema: $ref: '#/components/schemas/pickup_resource_id' rate_id_path_param: name: rate_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Rate ID rate_id_query_param: name: rate_id in: query required: false schema: $ref: '#/components/schemas/se_id' description: Rate ID sales_order_id_query_param: name: sales_order_id in: query required: false schema: type: string description: Sales Order ID ship_to_name_query_param: name: ship_to_name in: query required: false schema: type: string description: The name associated with the ship_to shipment_id_path_param: name: shipment_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Shipment ID shipment_id_query_param: name: shipment_id in: query required: false schema: $ref: '#/components/schemas/se_id' description: Shipment ID shipment_number_query_param: name: shipment_number in: query required: false schema: type: string description: The user or order source defined shipment number sort_dir_query_param: name: sort_dir in: query required: false schema: allOf: - $ref: '#/components/schemas/sort_dir' default: desc description: Controls the sort order of the query. store_id_query_param: name: store_id in: query required: false schema: $ref: '#/components/schemas/se_id' description: Store ID tag_name_path_param: name: tag_name in: path required: true schema: $ref: '#/components/schemas/tag_name' tracking_number_query_param: name: tracking_number in: query required: false schema: type: string minLength: 1 example: '9405511899223197428490' description: The tracking number associated with a shipment warehouse_id_path_param: name: warehouse_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Warehouse ID warehouse_id_query_param: name: warehouse_id in: query required: false schema: $ref: '#/components/schemas/se_id' description: Warehouse ID webhook_id_path_param: name: webhook_id in: path required: true schema: $ref: '#/components/schemas/se_id' description: Webhook ID