{ "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.\n", "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:\n increment: Increase inventory quantity for specified location.\n decrement: Decreate inventory quantity for specified location given a set of filters.\n 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.\n modify: Modify attributes on specified inventory. The filters work the same as for decrement transaction type.\n", "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.\nIf 0 or missing and the warehouse has On Hand inventory, the request will fail.\n", "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" }, "barcode": { "type": "string", "description": "Physical barcode label for warehouse location bins/shelves used during pick/pack operations", "example": "1234567890" } } } }, "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" }, "barcode": { "type": "string", "description": "Physical barcode label for warehouse location bins/shelves used during pick/pack operations. Optional field that accepts any string format.", "example": "1234567890" } } } } } }, "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" }, "barcode": { "type": "string", "description": "Physical barcode label for warehouse location bins/shelves used during pick/pack operations", "example": "1234567890" } } } } } } } } }, "/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" }, "barcode": { "type": "string", "description": "Physical barcode label for warehouse location bins/shelves used during pick/pack operations", "example": "1234567890" } } } } } } } }, "put": { "operationId": "updateInventoryLocation", "summary": "Update an inventory location", "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" }, "barcode": { "type": "string", "description": "Physical barcode label for warehouse location bins/shelves used during pick/pack operations. Optional field that accepts any string format.", "example": "1234567890" } } } } } }, "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.\nIf 0 or missing and the location has On Hand inventory, the request will fail.\n", "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.\nWhen 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.\n", "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.\n", "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.\n", "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.\n", "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.\nShipStation allows you to easily integrate with multiple carriers so you can choose the shipping services that are right for you.\n", "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.\n", "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.\n", "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.\n", "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.\nUse fulfillments to notify customers and marketplaces when orders have been shipped and to provide tracking details.\n", "get": { "summary": "List fulfillments", "description": "Retrieve a list of fulfillments based on various filter criteria. You can filter by shipment details,\ntracking information, dates, and more to find the specific fulfillments you need.\n", "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.\nThis will notify customers and marketplaces according to your configuration.\n", "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.\n", "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.\n\nBy 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`.\n", "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/refund_status_query_param", "description": "Only return labels with specific refund status/es." }, { "$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", "voided_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.\n", "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.\n", "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.\n", "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.\n", "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/rate_shopper_id/{rate_shopper_id}": { "x-visibility": "public", "summary": "Use Rate Shopper to purchase a label", "description": "Automatically select the optimal carrier and service based on your\nspecified strategy (cheapest, fastest, or best_value), then purchase\na label. The Rate Shopper analyzes available rates across your\nconnected carriers and selects the best option according to your strategy.\n", "parameters": [ { "$ref": "#/components/parameters/rate_shopper_id_path_param" } ], "post": { "summary": "Purchase label with rate shopper", "description": "Create a label using Rate Shopper to automatically select the best\ncarrier and service based on the specified strategy.\n\nFor more information about Rate Shopper strategies and use cases, see [Rate Shopping](/rate-shopping#automatic-label-creation-with-rate-shopper).\n", "tags": [ "labels" ], "operationId": "create_label_from_rate_shopper", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_label_rate_shopper_request_body" } } } }, "responses": { "200": { "description": "Label created successfully using Rate Shopper", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_label_rate_shopper_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.\n", "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/labels/{label_id}/cancel_refund": { "x-visibility": "public", "summary": "Cancel label refund request", "description": "Exclude labels from Refund Assist by canceling a scheduled refund request.\nThis endpoint allows you to prevent a label with \"request_scheduled\" refund\nstatus from being included in an upcoming automatic refund request.\n", "parameters": [ { "$ref": "#/components/parameters/label_id_path_param" } ], "post": { "summary": "Cancel a label refund request", "description": "Cancel a scheduled refund request for a label. Only labels with refund\nstatus \"request_scheduled\" can be excluded from an upcoming refund request.\n", "tags": [ "labels" ], "operationId": "cancel_label_refund", "responses": { "200": { "description": "The refund cancellation was successful. Returns the updated label object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/label" } } } }, "400": { "description": "Bad request. The label refund status is invalid or the request is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" }, "examples": { "invalid_refund_status": { "summary": "Invalid label refund status", "value": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "errors": [ { "error_source": "ShipStation", "error_type": "business_rules", "error_code": "invalid_status", "message": "Only labels with the Refund Status of Request Scheduled can be excluded from an upcoming refund request." } ] } } } } } }, "404": { "description": "The label_id was not found or does not belong to your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" }, "examples": { "invalid_identifier": { "summary": "Invalid label_id", "value": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "errors": [ { "error_source": "ShipStation", "error_type": "business_rules", "error_code": "invalid_identifier", "message": "Invalid label_id.", "field_name": "label_id", "field_value": "se-10659939" } ] } } } } } }, "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\noften physical manifests are not necessary. Carriers receive the package details, shipping date,\nand other information that help them plan your package's delivery when you create a label.\n\nHowever, 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.\n\nA manifest exists so the carrier can scan the manifest and check in all the packages being shipped.\n", "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\nrather than the ship_from address. You can create a warehouse for each location that you want to create manifests for.\n", "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\nthe `/packages` endpoint becomes useful. Create, manage, and delete custom package types to suit your specific needs.\n", "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\n", "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\n", "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\n", "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/purchase_orders": { "x-visibility": "public", "summary": "Purchase Orders", "description": "Manage purchase orders for inventory replenishment. Create, update, and track orders from suppliers.\n", "get": { "operationId": "list_purchase_orders", "summary": "List purchase orders", "description": "Retrieve a paginated list of purchase orders with optional filtering by status, warehouse, dates, and other criteria.\n", "tags": [ "purchase_orders" ], "parameters": [ { "name": "order_number", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by order number", "example": "02162026-02" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "open", "receiving", "received", "cancelled", "closed" ] }, "description": "Filter by status" }, { "name": "warehouse_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by warehouse ID" }, { "name": "reference_number", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by reference number" }, { "name": "create_date_start", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter by creation date start (inclusive)", "example": "2025-01-01T00:00:00Z" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 }, "description": "Number of results per page" } ], "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_orders": { "type": "array", "items": { "type": "object", "properties": { "purchase_order_id": { "type": "string", "description": "Unique identifier for the purchase order", "example": "se-234" }, "order_number": { "type": "string", "description": "Auto-generated order number", "example": "02162026-02" }, "supplier_id": { "type": "string", "description": "Supplier identifier", "example": "se-567" }, "supplier_name": { "type": "string", "description": "Name of the supplier", "example": "Acme Widgets Inc" }, "status": { "type": "string", "enum": [ "draft", "open", "receiving", "received", "cancelled", "closed" ], "description": "Current status of the purchase order", "example": "open" }, "order_date": { "type": "string", "format": "date-time", "description": "Date when the order was placed", "example": "2025-01-15T00:00:00Z" }, "expected_delivery_date": { "type": "string", "format": "date-time", "description": "Expected delivery date", "example": "2025-02-01T00:00:00Z" }, "create_date": { "type": "string", "format": "date-time", "description": "Date when the purchase order was created", "example": "2025-01-14T10:30:00Z" }, "modify_date": { "type": "string", "format": "date-time", "description": "Date when the purchase order was last modified", "example": "2025-01-14T10:30:00Z" }, "reference_number": { "type": "string", "description": "Optional reference number", "example": "REF-12345" }, "warehouse_id": { "type": "string", "description": "Warehouse identifier", "example": "se-123456" } } } }, "total": { "type": "integer", "description": "Total number of purchase orders", "example": 150 }, "page": { "type": "integer", "description": "Current page number", "example": 2 }, "pages": { "type": "integer", "description": "Total number of pages", "example": 3 }, "links": { "type": "object", "properties": { "first": { "type": "object", "properties": { "href": { "type": "string", "example": "https://api.shipstation.com/v2/purchase_orders?page_size=50" } } }, "next": { "type": [ "object", "null" ], "properties": { "href": { "type": "string", "example": "https://api.shipstation.com/v2/purchase_orders?cursor=eyJQYWdlIjoyLCJPcmRlck51bWJlciI6bnVsbCwiU3RhdHVzIjpudWxsLCJXYXJlaG91c2VJZCI6bnVsbCwiUmVmZXJlbmNlTnVtYmVyIjpudWxsLCJDcmVhdGVEYXRlU3RhcnQiOm51bGx9" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "operationId": "create_purchase_order", "summary": "Create a new purchase order", "description": "Create a new purchase order with products from a supplier.\n", "tags": [ "purchase_orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "supplier_id", "warehouse_id", "products" ], "properties": { "supplier_id": { "type": "string", "description": "Supplier identifier", "example": "se-567" }, "order_date": { "type": "string", "format": "date-time", "description": "Date when the order was placed", "example": "2025-01-15T00:00:00Z" }, "expected_delivery_date": { "type": "string", "format": "date-time", "description": "Expected delivery date", "example": "2025-02-01T00:00:00Z" }, "payment_terms": { "type": "string", "enum": [ "none", "cash_on_delivery", "payment_on_receipt", "payment_in_advance", "net_7", "net_15", "net_30", "net_45", "net_60" ], "description": "Payment terms for the order", "example": "net_30" }, "payment_status": { "type": "string", "enum": [ "none", "unpaid", "partially_paid", "paid", "refunded", "credit_issued", "other" ], "description": "Payment status for the order", "example": "unpaid" }, "currency_code": { "type": "string", "description": "ISO 4217 currency code", "example": "USD", "default": "USD" }, "shipping_carrier": { "type": "string", "description": "Shipping carrier name", "example": "UPS" }, "tracking_number": { "type": "string", "description": "Tracking number for the shipment", "example": "1Z12345E1234567890" }, "reference_number": { "type": "string", "description": "Optional reference number", "example": "REF-12345" }, "warehouse_id": { "type": "string", "description": "Warehouse identifier", "example": "se-123456" }, "note_to_supplier": { "type": "string", "description": "Note to include for the supplier", "example": "Please expedite delivery" }, "products": { "type": "array", "description": "List of products in the purchase order", "minItems": 1, "items": { "type": "object", "required": [ "sku", "quantity" ], "properties": { "sku": { "type": "string", "description": "SKU of the product", "example": "WIDGET-001" }, "supplier_sku": { "type": "string", "description": "Supplier's SKU for the product", "example": "SUPP-WIDGET-001" }, "quantity": { "type": "integer", "description": "Quantity to order", "minimum": 1, "example": 100 }, "cost": { "type": "number", "description": "Unit cost", "minimum": 0, "example": 9.99 } } } } } } } } }, "responses": { "200": { "description": "Purchase order created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_order_id": { "type": "string", "description": "Unique identifier for the created purchase order", "example": "se-234" }, "order_number": { "type": "string", "description": "Auto-generated order number", "example": "02162026-02" }, "supplier_id": { "type": "string", "example": "se-567" }, "status": { "type": "string", "enum": [ "draft", "open", "receiving", "received", "cancelled", "closed" ], "example": "draft" }, "order_date": { "type": "string", "format": "date-time", "example": "2025-01-15T00:00:00Z" }, "expected_delivery_date": { "type": "string", "format": "date-time", "example": "2025-02-01T00:00:00Z" }, "create_date": { "type": "string", "format": "date-time", "example": "2025-01-14T10:30:00Z" }, "modify_date": { "type": "string", "format": "date-time", "example": "2025-01-14T10:30:00Z" }, "payment_terms": { "type": "string", "enum": [ "none", "cash_on_delivery", "payment_on_receipt", "payment_in_advance", "net_7", "net_15", "net_30", "net_45", "net_60" ], "example": "net_30" }, "payment_status": { "type": "string", "enum": [ "none", "unpaid", "partially_paid", "paid", "refunded", "credit_issued", "other" ], "example": "unpaid" }, "currency_code": { "type": "string", "example": "USD" }, "shipping_carrier": { "type": "string", "example": "UPS" }, "tracking_number": { "type": "string", "example": "1Z12345E1234567890" }, "reference_number": { "type": "string", "example": "REF-12345" }, "warehouse_id": { "type": "string", "example": "se-123456" }, "note_to_supplier": { "type": "string", "example": "Please expedite delivery" }, "products": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "example": "WIDGET-001" }, "supplier_sku": { "type": "string", "example": "SUPP-WIDGET-001" }, "quantity": { "type": "integer", "example": 100 }, "cost": { "type": "number", "example": 9.99 } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v2/purchase_orders/{purchase_order_id}": { "parameters": [ { "name": "purchase_order_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The purchase order identifier", "example": "se-234" } ], "get": { "operationId": "get_purchase_order", "summary": "Get purchase order details", "description": "Retrieve detailed information about a specific purchase order including all products.\n", "tags": [ "purchase_orders" ], "responses": { "200": { "description": "Purchase order details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_order_id": { "type": "string", "example": "se-234" }, "order_number": { "type": "string", "example": "02162026-02" }, "supplier_id": { "type": "string", "example": "se-567" }, "status": { "type": "string", "enum": [ "draft", "open", "receiving", "received", "cancelled", "closed" ], "example": "open" }, "order_date": { "type": "string", "format": "date-time", "example": "2025-01-15T00:00:00Z" }, "expected_delivery_date": { "type": "string", "format": "date-time", "example": "2025-02-01T00:00:00Z" }, "create_date": { "type": "string", "format": "date-time", "example": "2025-01-14T10:30:00Z" }, "modify_date": { "type": "string", "format": "date-time", "example": "2025-01-14T10:30:00Z" }, "payment_terms": { "type": "string", "enum": [ "none", "cash_on_delivery", "payment_on_receipt", "payment_in_advance", "net_7", "net_15", "net_30", "net_45", "net_60" ], "example": "net_30" }, "payment_status": { "type": "string", "enum": [ "none", "unpaid", "partially_paid", "paid", "refunded", "credit_issued", "other" ], "example": "unpaid" }, "currency_code": { "type": "string", "example": "USD" }, "shipping_carrier": { "type": "string", "example": "UPS" }, "tracking_number": { "type": "string", "example": "1Z12345E1234567890" }, "reference_number": { "type": "string", "example": "REF-12345" }, "warehouse_id": { "type": "string", "example": "se-123456" }, "note_to_supplier": { "type": "string", "example": "Please expedite delivery" }, "products": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "example": "WIDGET-001" }, "supplier_sku": { "type": "string", "example": "SUPP-WIDGET-001" }, "quantity": { "type": "integer", "example": 100 }, "cost": { "type": "number", "example": 9.99 } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "update_purchase_order", "summary": "Update a purchase order", "description": "Update an existing purchase order.\n\nEditing limitations:\n- In the `draft` status, all fields can be edited.\n- Once a purchase order moves to any other status (open, receiving, received, cancelled, or closed),\nupdating via PUT is no longer allowed.\n- For purchase orders in `open` status, use the POST /v2/purchase_orders/{purchase_order_id}/shipping_details endpoint to update shipping-related details.\n", "tags": [ "purchase_orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "supplier_id", "warehouse_id", "products" ], "properties": { "supplier_id": { "type": "string", "example": "67890" }, "order_date": { "type": "string", "format": "date-time", "example": "2025-01-15T00:00:00Z" }, "expected_delivery_date": { "type": "string", "format": "date-time", "example": "2025-02-01T00:00:00Z" }, "payment_terms": { "type": "string", "enum": [ "none", "cash_on_delivery", "payment_on_receipt", "payment_in_advance", "net_7", "net_15", "net_30", "net_45", "net_60" ], "example": "net_30" }, "payment_status": { "type": "string", "enum": [ "none", "unpaid", "partially_paid", "paid", "refunded", "credit_issued", "other" ], "example": "unpaid" }, "currency_code": { "type": "string", "example": "USD" }, "shipping_carrier": { "type": "string", "example": "UPS" }, "tracking_number": { "type": "string", "example": "1Z12345E1234567890" }, "reference_number": { "type": "string", "example": "REF-12345" }, "warehouse_id": { "type": "string", "example": "se-123456" }, "note_to_supplier": { "type": "string", "example": "Please expedite delivery" }, "products": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "sku", "quantity" ], "properties": { "sku": { "type": "string", "example": "WIDGET-001" }, "supplier_sku": { "type": "string", "example": "SUPP-WIDGET-001" }, "quantity": { "type": "integer", "minimum": 1, "example": 100 }, "cost": { "type": "number", "minimum": 0, "example": 9.99 } } } } } } } } }, "responses": { "200": { "description": "Purchase order updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_order_id": { "type": "string", "example": "se-234" }, "order_number": { "type": "string", "example": "02162026-02" }, "supplier_id": { "type": "string", "example": "se-567" }, "status": { "type": "string", "enum": [ "draft", "open", "receiving", "received", "cancelled", "closed" ], "example": "open" }, "order_date": { "type": "string", "format": "date-time", "example": "2025-01-15T00:00:00Z" }, "expected_delivery_date": { "type": "string", "format": "date-time", "example": "2025-02-01T00:00:00Z" }, "create_date": { "type": "string", "format": "date-time", "example": "2025-01-14T10:30:00Z" }, "modify_date": { "type": "string", "format": "date-time", "example": "2025-01-14T10:30:00Z" }, "payment_terms": { "type": "string", "enum": [ "none", "cash_on_delivery", "payment_on_receipt", "payment_in_advance", "net_7", "net_15", "net_30", "net_45", "net_60" ], "example": "net_30" }, "payment_status": { "type": "string", "enum": [ "none", "unpaid", "partially_paid", "paid", "refunded", "credit_issued", "other" ], "example": "unpaid" }, "currency_code": { "type": "string", "example": "USD" }, "shipping_carrier": { "type": "string", "example": "UPS" }, "tracking_number": { "type": "string", "example": "1Z12345E1234567890" }, "reference_number": { "type": "string", "example": "REF-12345" }, "warehouse_id": { "type": "string", "example": "se-123456" }, "note_to_supplier": { "type": "string", "example": "Please expedite delivery" }, "products": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "example": "WIDGET-001" }, "supplier_sku": { "type": "string", "example": "SUPP-WIDGET-001" }, "quantity": { "type": "integer", "example": 100 }, "cost": { "type": "number", "example": 9.99 } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v2/purchase_orders/{purchase_order_id}/shipping_details": { "parameters": [ { "name": "purchase_order_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The purchase order identifier" } ], "x-visibility": "public", "post": { "operationId": "update_purchase_order_shipping_details", "summary": "Update purchase order shipping details", "description": "Update shipping-related details for a purchase order in `open` status.\n\nEditing limitations:\n- Once a purchase order moves to any higher status (receiving, received, cancelled, or closed),\nupdating shipping details is no longer allowed.\n- Only the following fields can be modified: shipping_carrier, payment_terms, payment_status,\norder_date, expected_delivery_date, note_to_supplier, tracking_number, currency_code, and reference_number.\n", "tags": [ "purchase_orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_date": { "type": "string", "format": "date-time", "example": "2025-01-15T00:00:00Z" }, "expected_delivery_date": { "type": "string", "format": "date-time", "example": "2025-02-01T00:00:00Z" }, "payment_terms": { "type": "string", "enum": [ "none", "cash_on_delivery", "payment_on_receipt", "payment_in_advance", "net_7", "net_15", "net_30", "net_45", "net_60" ], "example": "net_30" }, "payment_status": { "type": "string", "enum": [ "none", "unpaid", "partially_paid", "paid", "refunded", "credit_issued", "other" ], "example": "unpaid" }, "currency_code": { "type": "string", "example": "USD" }, "shipping_carrier": { "type": "string", "example": "UPS" }, "tracking_number": { "type": "string", "example": "1Z12345E1234567890" }, "reference_number": { "type": "string", "example": "REF-12345" }, "note_to_supplier": { "type": "string", "example": "Please expedite delivery" } } } } } }, "responses": { "200": { "description": "Purchase order shipping details updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_order_id": { "type": "string", "example": "se-234" }, "order_number": { "type": "string", "example": "02162026-02" }, "supplier_id": { "type": "string", "example": "se-567" }, "status": { "type": "string", "enum": [ "draft", "open", "receiving", "received", "cancelled", "closed" ], "example": "open" }, "order_date": { "type": "string", "format": "date-time", "example": "2025-01-15T00:00:00Z" }, "expected_delivery_date": { "type": "string", "format": "date-time", "example": "2025-02-01T00:00:00Z" }, "create_date": { "type": "string", "format": "date-time", "example": "2025-01-14T10:30:00Z" }, "modify_date": { "type": "string", "format": "date-time", "example": "2025-01-14T10:30:00Z" }, "payment_terms": { "type": "string", "enum": [ "none", "cash_on_delivery", "payment_on_receipt", "payment_in_advance", "net_7", "net_15", "net_30", "net_45", "net_60" ], "example": "net_30" }, "payment_status": { "type": "string", "enum": [ "none", "unpaid", "partially_paid", "paid", "refunded", "credit_issued", "other" ], "example": "unpaid" }, "currency_code": { "type": "string", "example": "USD" }, "shipping_carrier": { "type": "string", "example": "UPS" }, "tracking_number": { "type": "string", "example": "1Z12345E1234567890" }, "reference_number": { "type": "string", "example": "REF-12345" }, "warehouse_id": { "type": "string", "example": "se-123456" }, "note_to_supplier": { "type": "string", "example": "Please expedite delivery" }, "products": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "example": "WIDGET-001" }, "supplier_sku": { "type": "string", "example": "SUPP-WIDGET-001" }, "quantity": { "type": "integer", "example": 100 }, "cost": { "type": "number", "example": 9.99 } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v2/purchase_orders/{purchase_order_id}/status": { "parameters": [ { "name": "purchase_order_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The purchase order identifier", "example": "se-234" } ], "post": { "operationId": "update_purchase_order_status", "summary": "Update purchase order status", "description": "Update the status of a purchase order. Valid status transitions must be followed.\n", "tags": [ "purchase_orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "open", "receiving", "received", "cancelled", "closed" ], "description": "New status for the purchase order", "example": "open" } } } } } }, "responses": { "200": { "description": "Status updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_order_id": { "type": "string", "example": "se-234" }, "status": { "type": "string", "enum": [ "open", "receiving", "received", "cancelled", "closed" ], "example": "open" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v2/purchase_orders/{purchase_order_id}/receives": { "parameters": [ { "name": "purchase_order_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The purchase order identifier", "example": "se-234" } ], "post": { "operationId": "receives_purchase_order_products", "summary": "Receive purchase order products", "description": "Record receipt of products from a purchase order. This updates inventory levels\nand may automatically change purchase order status.\n", "tags": [ "purchase_orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product_receives" ], "properties": { "product_receives": { "type": "array", "description": "List of products being received", "minItems": 1, "items": { "type": "object", "required": [ "sku", "inventory_location_id" ], "properties": { "sku": { "type": "string", "description": "SKU of the product", "example": "WIDGET-001" }, "inventory_location_id": { "type": "string", "description": "Location where inventory is received", "example": "se-12345" }, "received_quantity": { "type": "integer", "description": "Quantity received and accepted. At least one of `received_quantity` or `rejected_quantity` must be provided and greater than 0.", "minimum": 1, "example": 95 }, "rejected_quantity": { "type": "integer", "description": "Quantity rejected (damaged, missing, etc.). At least one of `received_quantity` or `rejected_quantity` must be provided and greater than 0.", "minimum": 1, "example": 5 }, "lot": { "type": "string", "description": "Lot number. Note - Availability depends on your ShipStation account plan.", "example": "LOT-2025-001" }, "expiration_date": { "type": "string", "format": "date-time", "description": "Expiration date for the lot. Note - Availability depends on your ShipStation account plan.", "example": "2026-01-01T00:00:00Z" } } } } } } } } }, "responses": { "200": { "description": "Products received successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase_order_id": { "type": "string", "example": "se-234" }, "status": { "type": "string", "enum": [ "receiving", "received" ], "example": "receiving" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v2/purchase_orders/{purchase_order_id}/documents/order_summary": { "parameters": [ { "name": "purchase_order_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The purchase order identifier", "example": "se-234" } ], "get": { "operationId": "get_purchase_order_summary_pdf", "summary": "Get purchase order summary PDF", "description": "Download a PDF document containing the purchase order summary.\nAvailable for purchase orders with status: open, receiving, received, or closed.\n", "tags": [ "purchase_orders" ], "responses": { "200": { "description": "PDF document generated successfully", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v2/purchase_orders/{purchase_order_id}/documents/received_summary": { "parameters": [ { "name": "purchase_order_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The purchase order identifier", "example": "se-234" } ], "get": { "operationId": "get_purchase_order_received_summary_pdf", "summary": "Get purchase order received summary PDF", "description": "Download a PDF document containing the received products summary.\nAvailable for purchase orders with status: receiving, received, or closed.\n", "tags": [ "purchase_orders" ], "responses": { "200": { "description": "PDF document generated successfully", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/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;\nso we provide functionality to show you all your options!\n", "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.\nAdditionally, we realize that you may have your own identifier, you can set this by setting the `external_shipment_id` field in the request body.\n", "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\n", "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" } } }, "put": { "summary": "Update a shipment", "description": "Update an existing shipment's details including addresses, package information,\ncarrier service, and shipping options. Use this endpoint to modify shipment\ninformation before purchasing a label.\n\nNote: The following fields are read-only and cannot be updated: shipment_id,\ncreated_at, modified_at, shipment_status, tags, and total_weight.\n", "tags": [ "shipments" ], "operationId": "update_shipment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update_shipment_request_body" } } } }, "responses": { "200": { "description": "The shipment was updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shipment" } } } }, "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\nAn 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\nwould remove it from this process\n", "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\nbased on the carriers associated with your account\n", "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.\n", "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/suppliers": { "x-visibility": "public", "summary": "Suppliers", "description": "Manage suppliers for purchase orders. Create, update, and retrieve supplier information.\n", "get": { "operationId": "list_suppliers", "summary": "List suppliers", "description": "Retrieve a paginated list of all suppliers with optional filtering by supplier name.\n", "tags": [ "suppliers" ], "parameters": [ { "name": "supplier_name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by supplier name (partial match)" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 }, "description": "Number of results per page" } ], "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "suppliers": { "type": "array", "items": { "type": "object", "properties": { "supplier_id": { "type": "string", "description": "Unique identifier for the supplier", "example": "se-567" }, "supplier_name": { "type": "string", "description": "Name of the supplier", "example": "Acme Widgets Inc" }, "supplier_email": { "type": "string", "format": "email", "description": "Email address of the supplier", "example": "orders@acmewidgets.com" }, "address_line_1": { "type": "string", "description": "First line of address", "example": "123 Main St" }, "address_line_2": { "type": "string", "description": "Second line of address", "example": "Suite 100" }, "city": { "type": "string", "description": "City", "example": "Austin" }, "state": { "type": "string", "description": "State or province", "example": "TX" }, "postal_code": { "type": "string", "description": "Postal or ZIP code", "example": "78701" }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "US" }, "contact_name": { "type": "string", "description": "Contact person name", "example": "John Doe" }, "contact_phone": { "type": "string", "description": "Contact phone number", "example": "512-555-0100" } } } }, "total": { "type": "integer", "description": "Total number of suppliers", "example": 25 }, "page": { "type": "integer", "description": "Current page number", "example": 2 }, "pages": { "type": "integer", "description": "Total number of pages", "example": 3 }, "links": { "type": "object", "properties": { "first": { "type": "object", "properties": { "href": { "type": "string", "example": "https://api.shipstation.com/v2/suppliers?page_size=50" } } }, "next": { "type": [ "object", "null" ], "properties": { "href": { "type": "string", "example": "https://api.shipstation.com/v2/suppliers?cursor=eyJQYWdlIjoyLCJTdXBwbGllck5hbWUiOm51bGx9" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "operationId": "create_supplier", "summary": "Create a new supplier", "description": "Create a new supplier with contact and address information.\n", "tags": [ "suppliers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "supplier_name" ], "properties": { "supplier_name": { "type": "string", "description": "Name of the supplier", "example": "Acme Widgets Inc" }, "supplier_email": { "type": "string", "format": "email", "description": "Email address of the supplier", "example": "orders@acmewidgets.com" }, "address_line_1": { "type": "string", "description": "First line of address", "example": "123 Main St" }, "address_line_2": { "type": "string", "description": "Second line of address", "example": "Suite 100" }, "city": { "type": "string", "description": "City", "example": "Austin" }, "state": { "type": "string", "description": "State or province", "example": "TX" }, "postal_code": { "type": "string", "description": "Postal or ZIP code", "example": "78701" }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "US" }, "contact_name": { "type": "string", "description": "Contact person name", "example": "John Doe" }, "contact_phone": { "type": "string", "description": "Contact phone number", "example": "512-555-0100" } } } } } }, "responses": { "200": { "description": "Supplier created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier_id": { "type": "string", "description": "Unique identifier for the created supplier", "example": "se-567" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v2/suppliers/{supplier_id}": { "parameters": [ { "name": "supplier_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The supplier identifier", "example": "se-567" } ], "get": { "operationId": "get_supplier", "summary": "Get supplier details", "description": "Retrieve detailed information about a specific supplier.\n", "tags": [ "suppliers" ], "responses": { "200": { "description": "Supplier details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier_id": { "type": "string", "example": "se-567" }, "supplier_name": { "type": "string", "example": "Acme Widgets Inc" }, "supplier_email": { "type": "string", "format": "email", "example": "orders@acmewidgets.com" }, "address_line_1": { "type": "string", "example": "123 Main St" }, "address_line_2": { "type": "string", "example": "Suite 100" }, "city": { "type": "string", "example": "Austin" }, "state": { "type": "string", "example": "TX" }, "postal_code": { "type": "string", "example": "78701" }, "country_code": { "type": "string", "example": "US" }, "contact_name": { "type": "string", "example": "John Doe" }, "contact_phone": { "type": "string", "example": "512-555-0100" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "update_supplier", "summary": "Update a supplier", "description": "Update an existing supplier's information.\n", "tags": [ "suppliers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "supplier_name" ], "properties": { "supplier_name": { "type": "string", "example": "Acme Widgets Inc" }, "supplier_email": { "type": "string", "format": "email", "example": "orders@acmewidgets.com" }, "address_line_1": { "type": "string", "example": "123 Main St" }, "address_line_2": { "type": "string", "example": "Suite 100" }, "city": { "type": "string", "example": "Austin" }, "state": { "type": "string", "example": "TX" }, "postal_code": { "type": "string", "example": "78701" }, "country_code": { "type": "string", "example": "US" }, "contact_name": { "type": "string", "example": "John Doe" }, "contact_phone": { "type": "string", "example": "512-555-0100" } } } } } }, "responses": { "200": { "description": "Supplier updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier_id": { "type": "string", "description": "Unique identifier for the updated supplier", "example": "se-567" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v2/tags": { "x-visibility": "public", "summary": "Tags", "description": "Tags are simple text-based flags or identifiers. Tags can be used as a simple label,\nsuch as Guaranteed_Overnight or Fragile so shipments can be easily [queried later]\n", "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/totes": { "x-visibility": "public", "summary": "Totes", "description": "Manage totes used in warehouse picking and packing operations. List totes, create new totes in batch, and filter by warehouse.\n", "get": { "summary": "List totes", "description": "Get all totes for the seller, optionally filtered by warehouse.", "tags": [ "totes" ], "operationId": "listTotes", "parameters": [ { "$ref": "#/components/parameters/inventory_warehouse_id_query_param" } ], "responses": { "200": { "description": "List of totes", "content": { "application/json": { "schema": { "type": "object", "properties": { "totes": { "type": "array", "items": { "$ref": "#/components/schemas/tote" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Create totes in batch", "description": "Create multiple totes at once. Returns both successfully created totes and any failures.", "tags": [ "totes" ], "operationId": "createTotesBatch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tote_create_batch_request" } } } }, "responses": { "200": { "description": "Batch creation response with succeeded and failed totes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_create_tote_response" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/totes/quantities": { "x-visibility": "public", "summary": "Tote quantities by warehouse", "description": "Get tote counts grouped by warehouse.", "get": { "summary": "Get tote quantities", "description": "Get the number of totes in each warehouse.", "tags": [ "totes" ], "operationId": "getToteQuantities", "responses": { "200": { "description": "Tote quantities by warehouse", "content": { "application/json": { "schema": { "type": "object", "properties": { "quantities": { "type": "array", "items": { "$ref": "#/components/schemas/tote_quantity_response" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/totes/{tote_id}": { "x-visibility": "public", "summary": "Tote by ID", "description": "Get, update, or delete a specific tote by ID.", "get": { "summary": "Get tote by ID", "description": "Retrieve details of a specific tote.", "tags": [ "totes" ], "operationId": "getToteById", "parameters": [ { "$ref": "#/components/parameters/tote_id_path_param" } ], "responses": { "200": { "description": "Tote details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tote" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "summary": "Update tote", "description": "Update the name or barcode of an existing tote.", "tags": [ "totes" ], "operationId": "updateTote", "parameters": [ { "$ref": "#/components/parameters/tote_id_path_param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tote_update_request" } } } }, "responses": { "204": { "$ref": "#/components/responses/NoContent" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete tote", "description": "Delete a tote by its ID.", "tags": [ "totes" ], "operationId": "deleteTote", "parameters": [ { "$ref": "#/components/parameters/tote_id_path_param" } ], "responses": { "204": { "$ref": "#/components/responses/NoContent" }, "400": { "$ref": "#/components/responses/BadRequest" }, "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\nship_from and return_to addresses on every shipment. The solution is to [Create a Warehouse], then you can simply pass the warehouse_id instead.\n", "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\nship_from and return_to addresses on every shipment. The solution is to [Create a Warehouse], then you can simply pass the warehouse_id instead.\n", "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.\nWebhooks allow the ShipStation servers to contact your servers when an operation changes state, such as a batch label creation completion.\n", "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.\n", "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.\n", "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.\n", "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.\n", "x-displayName": "Carriers" }, { "name": "downloads", "description": "Download your label files in PDF, PNG, and ZPL.\n", "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.\n", "x-displayName": "Fulfillments" }, { "name": "inventory", "description": "Manage inventory levels, warehouses, and locations.\n", "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.\n", "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.\n", "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.\n", "x-displayName": "Package Types" }, { "name": "products", "description": "Manage products in your ShipStation account. Products represent the items you sell and ship to customers.\n", "x-displayName": "Products" }, { "name": "purchase_orders", "description": "Create and manage purchase orders from suppliers to replenish inventory. Track order status, receive products, and update inventory levels automatically.\n", "x-displayName": "Purchase Orders" }, { "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).\n", "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.\n", "x-displayName": "Shipments" }, { "name": "suppliers", "description": "Manage supplier information including contact details, email addresses, and physical addresses. Suppliers are used when creating purchase orders.\n", "x-displayName": "Suppliers" }, { "name": "tags", "description": "Tags are text-based identifiers you can add to shipments to help in your shipment management workflows.\n", "x-displayName": "Tags" }, { "name": "totes", "description": "Manage totes (bins or containers) used in warehouse picking and packing operations. Create, update, delete totes and track tote quantities by warehouse.\n", "x-displayName": "Totes" }, { "name": "tracking", "description": "Use the tracking endpoint to stop receiving tracking updates (more dedicated tracking endpoint methods coming soon).\n", "x-displayName": "Tracking" }, { "name": "warehouses", "description": "Get warehouse details like warehouse ID and related addresses using the warehouses endpoint.\n", "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.\n", "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.\n", "x-displayName": "Webhooks" } ], "components": { "securitySchemes": { "api_keys": { "description": "Generate your secret API key in the app settings.\n", "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\ncustom zones that vary depending upon the ship_to and ship_from location\n" }, "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\ntime if for example, the package gets shipped on a Friday\n" }, "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.\n", "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.\n", "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]\n", "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.\n\n> **Warning:** The `external_shipment_id` is limited to 50 characters. Any additional characters will be truncated.\n" }, "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.\n" }, "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.\n" }, "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.\n" }, "requested_comparison_amount": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/monetary_value" } ], "description": "The total shipping cost for the specified comparison_rate_type.\n" }, "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.\n" }, "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.\n" }, "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.\n" }, "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.\n" }, "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\n", "example": "se-1234567" }, "charge_event": { "allOf": [ { "$ref": "#/components/schemas/label_charge_event" } ], "description": "The label charge event.\n" }, "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\nrequired by some carriers.\n" }, "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.\n" }, "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.\n" }, "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]\n" }, "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\n" }, "void_type": { "x-nullable": true, "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/void_type" } ], "description": "Indicates how the label was voided. This field is `null` if the label has not been voided.\n", "example": "manual" }, "refund_details": { "x-nullable": true, "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/refund_details" } ], "description": "Information about the Refund Assist request for this label. This field is `null` if the label is not eligible for Refund Assist.\n" }, "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.\n" }, "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.\n" }, "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`.\n" }, "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.\n" }, "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.\n" }, "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`.\n" }, "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.\n" }, "packages": { "type": "array", "readOnly": true, "description": "The label's package(s).\n\n> **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.\n", "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.\n", "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.\n", "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.\n" }, "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\nthousands of labels at a time.\n", "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://example.com/webhook", "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.\n" }, "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.\n" }, "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.\n" }, "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`.\n" } } }, "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.\n", "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.\n\n> **Note:** Either `ship_from` or `warehouse_id` must be set.\n", "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.\n", "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.\n", "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\n", "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\nexternal order sources\n" }, "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.\n\n> **Warning:** The `external_shipment_id` is limited to 50 characters. Any additional characters will be truncated.\n" }, "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.\n\n> **Warning:** The `shipment_number` is limited to 50 characters. Any additional characters will be truncated.\n" }, "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.\n" }, "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.\n" }, "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.\n" }, "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.\n" }, "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.\n", "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.\n" }, "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.\n" }, "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.\n" }, "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.\n\n> **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.\n" }, "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" } } }, "partial_shipment_for_rate_shopper": { "title": "partial_shipment_for_rate_shopper", "type": "object", "description": "Shipment information for Rate Shopper. Must NOT include carrier_id, service_code, \nor shipping_rule_id as Rate Shopper selects these automatically.\n", "additionalProperties": false, "properties": { "shipment_id": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "A string that uniquely identifies the shipment" }, "requested_shipment_service": { "type": "string", "x-nullable": true, "description": "The requested shipment service", "example": "usps_priority_mail" }, "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\nexternal order sources\n" }, "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.\n\n> **Warning:** The `external_shipment_id` is limited to 50 characters. Any additional characters will be truncated.\n" }, "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.\n\n> **Warning:** The `shipment_number` is limited to 50 characters. Any additional characters will be truncated.\n" }, "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.\n" }, "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.\n" }, "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.\n" }, "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.\n" }, "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.\n", "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.\n" }, "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.\n" }, "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.\n" }, "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.\n\n> **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.\n" }, "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.\n", "required": [ "currency", "amount" ], "additionalProperties": false, "properties": { "currency": { "allOf": [ { "$ref": "#/components/schemas/currency" } ], "description": "Currency code", "example": "usd" }, "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.\n", "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.\n", "example": "any instructions" } } }, "address": { "title": "address", "type": "object", "description": "Any residential or business mailing address, anywhere in the world.\n\n> **Note:** Either `name` or `company_name` must be set. Both may be specified, if relevant.\n", "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.\n" }, "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.\n" }, "email": { "type": "string", "x-nullable": true, "example": "example@example.com", "description": "Email for the address owner.\n" }, "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.\n" }, "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.\n" }, "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.\n" }, "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.\n" }, "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.\n" }, "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)\n" }, "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\n", "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.\n", "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\ncustom zones that vary depending upon the ship_to and ship_from location\n" }, "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\ntime if for example, the package gets shipped on a Friday\n" }, "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": "2024-10-22T00:00:00Z", "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.\n", "additionalProperties": false, "properties": { "type": { "type": "string", "minLength": 1, "example": "last_mile_tracking_number", "description": "The type of alternative_identifier that corresponds to the value.\n" }, "value": { "type": "string", "minLength": 1, "example": "12345678912345678912", "description": "The value of the alternative_identifier.\n" } } }, "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]\n", "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.\n" }, "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.\n" }, "tracking_number": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/tracking_number" } ], "description": "The tracking number for the package. The format depends on the carrier.\n" }, "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.\n", "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\n", "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.\n", "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.\n" }, "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.\n" }, "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.\n", "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\n" }, "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.\n\n|Carrier |Max lines |Max line length\n|-------------------|----------|--------------------\n|USPS (Stamps.com) |3 |60\n|FedEx |3 |35 for the first line. 30 for additional lines.\n|UPS |2 |35\n|OnTrac |2 |25\n", "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.\n", "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.\n", "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.\n", "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\n", "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`.\n", "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.\n", "example": "any instructions" }, "handoff_code": { "type": "string", "x-nullable": true, "default": null, "example": "122334", "description": "The handoff code for the paperless download.\n" } } }, "label_download": { "title": "label_download", "type": "object", "description": "Reference to the various downloadable file formats for the generated label\n", "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.\n", "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.\n", "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.\n", "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.\n", "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.\n", "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.\n", "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.\n", "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\".\n" }, "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.\n", "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.\n", "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.\n", "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.\n", "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 }, "fragile": { "type": "boolean", "default": false, "description": "Indicates if the shipment contains fragile items", "example": false }, "delivery_as_addressed": { "type": "boolean", "default": false, "description": "Instructs the carrier to deliver the package only to the exact address provided", "example": false }, "return_after_first_attempt": { "type": "boolean", "default": false, "description": "Ensures the shipment is immediately flagged for return to the sender if the initial delivery attempt fails", "example": false }, "regulated_content_type": { "x-nullable": true, "default": null, "allOf": [ { "$ref": "#/components/schemas/regulated_content_type" } ], "description": "Indicates the category of goods in the shipment that is subject to special regulatory or compliance requirements" } } }, "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\n", "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\n", "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.\n", "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.\n" }, "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.\n" }, "email": { "type": "string", "x-nullable": true, "example": "example@example.com", "description": "Email for the address owner.\n" }, "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.\n" }, "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.\n" }, "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.\n" }, "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.\n" }, "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.\n" }, "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)\n" } } }, "invoice_additional_details": { "title": "invoice_additional_details", "type": "object", "description": "The additional information to put on commercial invoice\n", "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.\n", "example": "any instruction" }, "geolocation": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "what3words", "description": "Enum of available type of geolocation items:\n - '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.\n", "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\nthat has been tied to the current account.\n", "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.\n" }, "account_number": { "type": "string", "readOnly": true, "minLength": 1, "example": "account_570827", "description": "The account number that the carrier is connected to." }, "connection_status": { "type": "string", "readOnly": true, "x-nullable": true, "enum": [ "pending_approval", "approved" ], "description": "The connection status of the carrier account. Indicates whether the carrier connection is pending approval or has been approved. This only applies to certain carriers; it can be undefined.", "example": "approved" }, "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.\n" }, "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_code", "readOnly": true } ], "example": "IT" }, "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\n", "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_code", "readOnly": true } ], "example": "IT" }, "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", "pickup_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\nnumber of shipments\n", "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\n", "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.\nThis can be given to the support team to help debug non-trivial issues that may occur\n" }, "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\n", "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" }, "field_name": { "type": "string", "readOnly": true, "example": "inventory_warehouse_id", "description": "The name of the field that caused the error (only present for validation errors)" }, "field_value": { "type": "string", "readOnly": true, "example": "invalid-id", "description": "The invalid value that was provided for the field (only present for validation errors)" } } }, "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", "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_id", "label_ids", "created_at", "carrier_id", "warehouse_id", "pickup_address", "contact_details", "pickup_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" } ] }, "create_label_rate_shopper_response_body": { "title": "create_label_rate_shopper_response_body", "type": "object", "description": "Response from creating a label using Rate Shopper", "allOf": [ { "$ref": "#/components/schemas/label" } ], "properties": { "rate_shopper_id": { "type": "string", "readOnly": true, "description": "The Rate Shopper strategy used to create this label", "example": "cheapest", "enum": [ "cheapest", "fastest", "best_value" ] } } }, "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`.\n", "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.\nThis can be given to the support team to help debug non-trivial issues that may occur\n" }, "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.\n\n|Label Format | Supported Carriers\n|--------------|-----------------------------------\n|`pdf` | All carriers\n|`png` | `fedex`
`stamps_com`
`ups`
`usps`\n|`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`\n" }, "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\n\n|Value |Description\n|:--------- |:-----------------------------------------------------\n| `COLLECTION_FAILED` | Shipment pickup failed. The delivery company will try again soon.\n| `AWAITING_DESPATCH` | Your shipment is ready to go and is waiting for pickup.\n| `COLLECTION_REQUESTED` | Your shipment pickup has been scheduled.\n| `DESPATCHED` | Your shipment has been handed over to the carrier or dropped off at collection point. It will soon start its journey.\n| `ELEC_ADVICE_RECD_BY_CARRIER` | Your shipment is now in the carrier's system.\n| `NOT_YET_RECEIVED_BY_CARRIER` | The sender couldn't hand over your shipment. The delivery company will try to collect it again.\n| `COLLECTION_MADE` | Your shipment has been picked up by the carrier.\n| `ATTEMPTED_DELIVERY` | Delivery attempt failed. Please check the carrier's instructions for next steps.\n| `ATTEMPTED_DELIVERY_2ND` | Second delivery attempt failed. Please check the carrier's instructions for next steps.\n| `ATTEMPTED_DELIVERY_3RD` | Third delivery attempt failed. Please check the carrier's instructions for next steps.\n| `COD_AMOUNT_NOT_PAID` | Delivery failed due to unpaid cash on delivery. Please check carrier instructions.\n| `COD_AMOUNT_PAID` | Cash on delivery payment received.\n| `CUSTOMER_CARDED` | Delivery attempt failed. Please check for delivery instructions left by the carrier.\n| `CUSTOMER_IDENTIFICATION_FAILED` | There was a recipient identification issue. Please check carrier instructions.\n| `INVALID_METHOD_OF_PAYMENT` | Delivery failed due to incorrect payment. Please check carrier instructions.\n| `NO_ACCESS_TO_RECIPIENTS_ADDRESS` | Delivery couldn't be completed due to issues with accessing address. Please follow carrier instructions.\n| `OUT_FOR_DELIVERY` | Your shipment is out for delivery.\n| `DELIVERED` | Your shipment has been delivered.\n| `DELIVERED_DAMAGED` | Your shipment was delivered but arrived damaged.\n| `DELIVERED_IN_PART` | Part of your shipment has been delivered. Check for updates on the rest.\n| `DELIVERED_SPECIFIED_SAFE_PLACE` | Your shipment has been left in your designated safe place.\n| `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.\n| `DELIVERED_TO_NEIGHBOUR` | Your shipment was delivered to your neighbor.\n| `DELIVERED_TO_PO_BOX` | Your shipment was delivered to your PO Box.\n| `PARCEL_COLLECTED_FROM_PICKUP_POINT` | Your package has been picked up from the collection point.\n| `POST_TRANSIT_STATUS` | The carrier has added more information about your delivery.\n| `PROOF_OF_DELIVERY` | Delivery confirmed.\n| `CANCELLED` | Your shipment has been cancelled.\n| `CANCELLED_BEFORE_DESPATCH` | Your shipment was cancelled before pickup. Contact the sender if unexpected.\n| `CUSTOMER_MOVED` | Recipient not at address. Your shipment is being returned.\n| `HAZARDOUS_PROHIBITED` | Your parcel contained a prohibited item and is being returned. Contact the sender.\n| `NOT_COLLECTED_FROM_PICKUP_POINT` | Shipment not collected from the pickup point. Your parcel is being returned to the sender.\n| `NOT_DELIVERED` | Delivery attempts failed. Your parcel is being returned to the sender.\n| `NOT_DELIVERED_ADDRESSEE_DECEASED` | Delivery not possible due to recipient's passing.\n| `PARCEL_DAMAGED` | Your parcel was damaged and can't be delivered. It's being returned. Contact the sender.\n| `PARCEL_DISPOSED` | Shipment was disposed of. Contact the sender for details.\n| `PARCEL_LOST` | Your parcel is lost. Contact the sender for next steps.\n| `PARCEL_OUTSIDE_OF_SERVICE_CAPABILITY` | Shipment is too large/heavy for delivery. Being returned. Contact sender.\n| `REFUSED_BY_CUSTOMER` | Delivery refused. Shipment being returned. Contact the sender.\n| `RETURN_TO_SENDER` | Your shipment is being returned to the sender. Contact them for details.\n| `ADDRESS_QUERY` | There's an issue with your delivery address. This may cause a delay or return. Contact sender or carrier.\n| `CARRIER_DELAYS` | There's a delivery delay. We'll update you when there's more info.\n| `CUSTOMS_CLEARED` | Your shipment has passed customs clearance.\n| `CUSTOMS_PROCESSING` | Your shipment is going through customs.\n| `DELAYED_NOT_CARRIER` | Unexpected delivery delay. We'll update you soon.\n| `DELIVERY_ARRANGED_WITH_RECIPIENT` | Delivery arranged by recipient.\n| `HELD_BY_CARRIER` | Your shipment is on hold due to a carrier issue. We'll update you soon.\n| `HELD_BY_CARRIER_FOR_CLEARANCE_PRE_PROCESSING` | Your shipment is held by carrier due to customs issues. We'll update you.\n| `HELD_BY_CUSTOMS` | Your shipment is held in customs. We'll update you.\n| `HELD_BY_EXPORT_CUSTOMS` | Your shipment is held in export customs. We'll update you.\n| `HELD_BY_IMPORT_CUSTOMS` | Your shipment is held in import customs. We'll update you.\n| `HUB_SCAN_OUT` | Your shipment is at the main delivery depot.\n| `IN_TRANSIT` | Your shipment is on its way between depots.\n| `INCORRECT_DECLARATION` | Incorrect shipment dimensions. Delivery may be delayed or returned. We'll update you.\n| `INFORMATION` | The carrier has shared additional shipment information.\n| `MISSORTED` | Your shipment was missorted. There might be a delivery delay. We'll update you.\n| `PARCEL_OVER_LABELLED` | Your shipment was over labelled by the delivery company to improve processing.\n| `PARCEL_REPACKED` | Your shipment packaging was damaged. It's being repacked. This might delay delivery.\n| `PARCEL_UPDATE_NOTIFICATION_VIA_EMAIL` | You've received an email with a shipment update.\n| `PARCEL_UPDATE_NOTIFICATION_VIA_SMS` | You've received a text message with a shipment update.\n| `RECEIVED_BY_CARRIER` | Your shipment has been received by the carrier.\n| `RECEIVED_LOCAL_DELIVERY_DEPOT` | Your shipment is at the local delivery depot, ready for delivery.\n| `ROUTING_ERROR` | Your shipment was sent to the wrong place. There might be a delay.\n| `SUB_CONTRACTOR_EVENT` | Your shipment is with the local delivery partner.\n| `SUB_CONTRACTOR_RECEIVED` | Your shipment has been received by the local delivery partner.\n| `RECD_BY_CARRIER_NO_ELEC_ADVICE` | There's a system issue with your shipment. Tracking updates might be delayed.\n| `AWAITING_ELECTRONIC_ADVICE` | Your tracking number is ready. Your shipment is waiting to be registered in the carrier system and scheduled for pickup.\n| `AWAITING_COLLECTION_FROM_PICKUP_POINT` | Your shipment is ready for pickup at the specified location.\n| `COLLECT_AT_LOCAL_PO` | Your shipment has been redirected to the local post office for pickup. Check carrier instructions.\n| `CUSTOMER_TO_COLLECT_FROM_CARRIER` | Your shipment is being held for pickup. Check carrier instructions.\n| `DELIVERED_TO_LOCKER_COLLECTION_POINT` | Your shipment has been delivered to your locker.\n| `CARRIER_STATUS_NOT_MAPPED` | Status not mapped. Please check the carrier's website for updates.\n" }, "tracking_status_code": { "title": "status_code", "enum": [ "UN", "AC", "IT", "DE", "EX", "AT", "NY", "SP" ], "type": "string", "description": "The high-level tracking status codes\n\n|Value |Description\n|:--------- |:-----------------------------------------------------\n|`UN` | Unknown\n|`AC` | Accepted\n|`IT` | In Transit\n|`DE` | Delivered\n|`EX` | Exception\n|`AT` | Delivery Attempt\n|`NY` | Not Yet In System\n|`SP` | Delivered To Collection Location\n" }, "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\n\n|Pickup Type | Description\n|---------------|-----------------------------------------\n|`vat` | The tax identifier is a Value Added Tax.\n|`eori` | The tax identifier is an Economic Operators Registration and Identification Number (EORI).\n|`ssn` | The tax identifier is a Social Security Number.\n|`ein` | The tax identifier is an Employer Identification Number (EIN).\n|`tin` | The tax identifier is a Tax Identification Number (TIN).\n|`ioss` | The tax identifier is an Import One-Stop Shop (IOSS).\n|`pan` | The tax identifier is a Permanent Account Number (PAN).\n|`voec` | The tax identifier is a Norwegian VAT On E-Commerce(VOEC).\n|`pccc` | The tax identifier is a Personal Customs Clearance Code (PCCC).\n|`oss` | The tax identifier is an One-Stop Shop (OSS).\n|`passport` | The tax identifier is a Passport Number.\n|`abn` | The tax identifier is an Australian Business Number.\n|`ukims` | The tax identifier is an UK Internal Market Scheme number.\n" }, "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\n\n|Value |Description\n|:--------- |:-----------------------------------------------------\n|`shipper` | The shipper is responsible for this tax.\n|`recipient` | The recipient of the shipment is responsible for this tax.\n|`ior` | The importer of records is responsible for tax.\n" }, "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" }, "regulated_content_type": { "title": "regulated_content_type", "type": "string", "enum": [ "day_old_poultry", "other_live_animal" ], "description": "Indicates the category of goods in the shipment that is subject to special regulatory or compliance requirements" }, "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\n" }, "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\ncarrier, the order source, or the ShipStation API itself.\n" }, "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" }, "refund_details": { "title": "refund_details", "type": "object", "description": "Information about a Refund Assist label. This object contains details about the refund request status and associated monetary amounts.\n", "additionalProperties": false, "properties": { "refund_status": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/refund_status" } ], "description": "The current status of the refund request" }, "request_date": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/date_time" } ], "description": "The date and time when the refund request was submitted" }, "amount_paid": { "readOnly": true, "x-nullable": true, "allOf": [ { "$ref": "#/components/schemas/monetary_value" } ], "description": "The amount that was originally paid for the label" }, "amount_requested": { "readOnly": true, "x-nullable": true, "allOf": [ { "$ref": "#/components/schemas/monetary_value" } ], "description": "The amount requested to be refunded" }, "amount_approved": { "readOnly": true, "x-nullable": true, "allOf": [ { "$ref": "#/components/schemas/monetary_value" } ], "description": "The amount approved for refund by the carrier" }, "amount_credited": { "readOnly": true, "x-nullable": true, "allOf": [ { "$ref": "#/components/schemas/monetary_value" } ], "description": "The amount that has been credited back to the account" } } }, "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\n" }, "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" }, "void_type": { "title": "void_type", "type": "string", "enum": [ "refund_assist", "manual" ], "description": "Indicates how a label was voided. `refund_assist` means the label was voided through the Refund Assist program, while `manual` means it was voided manually by the user." }, "refund_status": { "title": "refund_status", "type": "string", "enum": [ "request_scheduled", "pending", "approved", "rejected", "excluded" ], "example": "request_scheduled", "description": "The status of a Refund Assist request for eligible labels.\n\n|Status |Description\n|:-------------------|:-----------------------------------------------------\n|`request_scheduled` |The refund request has been scheduled but not yet submitted\n|`pending` |The refund request has been submitted and is awaiting approval\n|`approved` |The refund request has been approved by the carrier\n|`rejected` |The refund request has been rejected by the carrier\n|`excluded` |The refund request has been excluded by the user. Labels in this status were not sent to the carrier for a refund request.\n" }, "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", "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.\n" }, "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", "delivery_code", "age_verification_16_plus" ], "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.\n\n|Status |Description\n|:------------|:-----------------------------------------------------\n|`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.\n|`completed` |The label was successfully created\n|`error` |The label could not be created due to an error, such as an invalid delivery address\n|`voided` |The label has been [voided]\n" }, "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]:\n\n|Label Download Type | Description\n|--------------------|------------------------------\n|`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.\n|`inline` |You will receive the Base64-encoded label as part of the response. No need for a second request to download the label.\n" }, "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\n\n|Value |Description\n|:---------|:-----------------------------------------------------\n|`asc` |Return results in ascending order\n|`desc` |Return results in descending order\n" }, "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.\n" }, "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.\n" }, "date": { "title": "date", "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[-+]\\d{2}:\\d{2}))?$", "example": "2018-09-23T00:00:00Z", "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 .\n" }, "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)\n" }, "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.\n" }, "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.\n" }, "tote": { "title": "tote", "type": "object", "description": "A tote (bin or container) used in warehouse picking and packing operations", "required": [ "tote_id", "inventory_warehouse_id", "tote_name", "created_at" ], "properties": { "tote_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "Unique identifier for the tote", "example": "se-123456" }, "inventory_warehouse_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The warehouse this tote belongs to", "example": "se-789012" }, "tote_name": { "type": "string", "maxLength": 100, "description": "Name of the tote", "example": "Tote-A1" }, "tote_barcode": { "type": "string", "maxLength": 100, "description": "Barcode identifier for the tote", "example": "TOTE123456" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the tote was created", "example": "2024-01-15T10:30:00Z" } } }, "tote_quantity_response": { "title": "tote_quantity_response", "type": "object", "description": "Tote quantity grouped by warehouse", "required": [ "inventory_warehouse_id", "quantity" ], "properties": { "inventory_warehouse_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The warehouse ID", "example": "se-789012" }, "quantity": { "type": "integer", "description": "Number of totes in this warehouse", "example": 25 } } }, "tote_create_request": { "title": "tote_create_request", "type": "object", "description": "Request to create a new tote", "required": [ "inventory_warehouse_id", "tote_name" ], "properties": { "inventory_warehouse_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The warehouse where this tote will be created", "example": "se-789012" }, "tote_name": { "type": "string", "maxLength": 100, "description": "Name for the new tote", "example": "Tote-B5" }, "tote_barcode": { "type": "string", "maxLength": 100, "description": "Barcode identifier for the tote (optional)", "example": "TOTE789012" } } }, "tote_create_batch_request": { "title": "tote_create_batch_request", "type": "object", "description": "Request to create multiple totes in batch", "required": [ "totes" ], "properties": { "totes": { "type": "array", "description": "Array of totes to create", "items": { "$ref": "#/components/schemas/tote_create_request" } }, "return_succeeded_totes": { "type": "boolean", "description": "Whether to include successfully created totes in the response. When false, only failed_totes will be returned.", "example": false, "default": false } } }, "bulk_create_tote_response": { "title": "bulk_create_tote_response", "type": "object", "description": "Response for batch tote creation", "properties": { "succeeded_totes": { "type": "array", "description": "Totes that were successfully created", "items": { "$ref": "#/components/schemas/tote" } }, "failed_totes": { "type": "array", "description": "Totes that failed to be created", "items": { "$ref": "#/components/schemas/failed_tote_response" } } } }, "failed_tote_response": { "title": "failed_tote_response", "type": "object", "description": "Information about a failed tote creation", "properties": { "inventory_warehouse_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The warehouse ID from the failed request", "example": "se-789012" }, "tote_name": { "type": "string", "description": "The tote name from the failed request", "example": "Tote-C3" }, "tote_barcode": { "type": "string", "description": "The tote barcode from the failed request", "example": "TOTE456789" }, "error_message": { "type": "string", "description": "Error message explaining why creation failed", "example": "A tote with this name already exists in the warehouse" } } }, "tote_update_request": { "title": "tote_update_request", "type": "object", "description": "Request to update an existing tote", "required": [ "inventory_warehouse_id", "tote_name" ], "properties": { "inventory_warehouse_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The warehouse where this tote is located", "example": "se-789012" }, "tote_name": { "type": "string", "maxLength": 100, "description": "Updated name for the tote", "example": "Tote-B5-Updated" }, "tote_barcode": { "type": "string", "maxLength": 100, "description": "Updated barcode for the tote", "example": "TOTE789012-NEW" } } }, "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.\n" }, "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://example.com/webhook", "description": "The url that the webhook 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://example.com/webhook", "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.\n" }, "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.\n" }, "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.\n" }, "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" } } }, "create_label_rate_shopper_request_body": { "title": "create_label_rate_shopper_request_body", "type": "object", "description": "Request body for creating a label using Rate Shopper", "required": [ "shipment" ], "additionalProperties": false, "properties": { "shipment": { "allOf": [ { "$ref": "#/components/schemas/partial_shipment_for_rate_shopper" } ], "description": "Shipment details. Must NOT include carrier_id, service_code, or\nshipping_rule_id as Rate Shopper selects these automatically.\n" }, "label_format": { "type": "string", "default": "pdf", "allOf": [ { "$ref": "#/components/schemas/label_format" } ] }, "label_layout": { "type": "string", "default": "4x6", "allOf": [ { "$ref": "#/components/schemas/label_layout" } ] }, "display_scheme": { "type": "string", "default": "label", "allOf": [ { "$ref": "#/components/schemas/display_scheme" } ] }, "label_download_type": { "type": "string", "enum": [ "url", "inline" ], "default": "url", "example": "url", "description": "Specifies how the label should be downloaded.\n- url: Returns URLs to download the label\n- inline: Returns the label data inline in the response\n" } } }, "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.\n" }, "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" } } } ] }, "update_shipment_request_body": { "title": "update_shipment_request_body", "type": "object", "description": "Request body for updating an existing shipment", "additionalProperties": false, "allOf": [ { "$ref": "#/components/schemas/partial_shipment" }, { "title": "update_shipment_fields", "type": "object", "properties": { "validate_address": { "default": "no_validation", "allOf": [ { "$ref": "#/components/schemas/validate_address" } ], "description": "Address validation option for ship_to and ship_from addresses" } } } ] }, "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.\n" }, "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.\n" }, "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_shopper_id_path_param": { "name": "rate_shopper_id", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "cheapest", "fastest", "best_value" ] }, "description": "The rate selection strategy. Determines which carrier and service\nwill be automatically selected:\n- cheapest: Lowest cost option\n- fastest: Fastest option at the lowest price\n- best_value: Lowest cost option arriving within 4 days\n" }, "rate_id_query_param": { "name": "rate_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/se_id" }, "description": "Rate ID" }, "refund_status_query_param": { "name": "refund_status", "in": "query", "required": false, "explode": false, "style": "form", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/refund_status" } }, "example": [ "pending", "approved" ] }, "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" } }, "tote_id_path_param": { "name": "tote_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/se_id" }, "description": "Tote ID" }, "inventory_warehouse_id_query_param": { "name": "inventory_warehouse_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/se_id" }, "description": "Inventory Warehouse ID to filter totes" }, "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" } } } }