{ "openapi": "3.1.0", "info": { "title": "ShipStation API v2", "version": "2.0.0", "description": "The ShipStation API v2 is a REST API for managing shipping, including rates, labels, batch labels, return labels, manifests, and more.\n\nIf you're new to REST APIs, read the [introduction to REST](https://docs.shipstation.com/rest) and learn how to [authenticate](https://docs.shipstation.com/authentication) before making your first request.\n", "contact": { "name": "ShipStation API Support", "url": "https://www.shipstation.com/support/" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/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", "description": "\n\nLists the inventory-related properties (`on_hand`, `allocated`, `available` and `average_cost`) of the SKUs that use inventory in your account. Filter by `sku`, `inventory_warehouse_id` or `inventory_location_id`.", "tags": [ "inventory" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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", "description": "\n\nUpdates the stock levels and other inventory-related properties of your SKUs.", "tags": [ "inventory" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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\n- `increment`: Increase inventory quantity for specified location.\n- `decrement`: Decrease 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.\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", "description": "\n\nLists all inventory warehouses in your account.", "tags": [ "inventory" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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", "description": "\n\nCreates an inventory warehouse. `name` is the only property you can define; `inventory_warehouse_id` is generated automatically.", "tags": [ "inventory" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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", "description": "\n\nReturns a single inventory warehouse by its `inventory_warehouse_id`.", "tags": [ "inventory" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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", "description": "\n\nUpdates the name of an existing inventory warehouse.", "tags": [ "inventory" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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", "description": "\n\nDeletes an inventory warehouse. The request fails if the warehouse has on-hand inventory, unless you set the `remove_inventory` query parameter to `1` to remove all of its inventory in the same request.", "tags": [ "inventory" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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", "description": "\n\nLists all inventory locations and shows which inventory warehouse each one belongs to.", "tags": [ "inventory" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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", "description": "\n\nCreates an inventory location in an inventory warehouse. The `name` must follow the area - unit - shelf - bin layout defined in ShipStation, for example `A1 - 12 - B2 - 24`.", "tags": [ "inventory" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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", "description": "\n\nReturns a single inventory location by its `inventory_location_id`, including the inventory warehouse it belongs to.", "tags": [ "inventory" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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", "description": "\n\nUpdates the name and/or barcode of an existing inventory location.", "tags": [ "inventory" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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", "description": "\n\nDeletes an inventory location. All inventory must be removed from the location before it can be deleted.", "tags": [ "inventory" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nList the batches associated with your ShipStation account.\n", "operationId": "list_batches", "tags": [ "batches" ], "x-plan": [ "ss-api-free_plan", "ss-standard_and_premium_plans", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nCreate a batch containing multiple labels.", "tags": [ "batches" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "create_batch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_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": "\n\nRetreive a batch using an external batch ID", "tags": [ "batches" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nDelete a batch based on its batch ID. Sets its status to 'archived'.", "operationId": "delete_batch", "tags": [ "batches" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nGet batch details for a specific batch ID.", "tags": [ "batches" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nUpdate a batch by ID setting its status to 'archived'.", "operationId": "update_batch", "tags": [ "batches" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nAdd a shipment or rate to a batch.", "tags": [ "batches" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "add_to_batch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/add_to_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": "\n\nErrors 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" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nCreate and purchase the labels for the shipments included in the batch.", "tags": [ "batches" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nRemove specific shipment ids or rate ids from a batch.", "tags": [ "batches" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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/batches/{batch_id}/user": { "x-visibility": "public", "summary": "User assigned to a batch", "description": "Assign a ShipStation user to a batch, or remove the current assignment.\n", "parameters": [ { "$ref": "#/components/parameters/batch_id_path_param" } ], "put": { "summary": "Assign user to a batch", "description": "\n\nAssign a user to a batch. Assigning a user replaces any existing assignment.", "tags": [ "batches" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "assign_user_to_batch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/assign_user_to_batch_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": "Unassign user from a batch", "description": "\n\nRemove the user assignment from a batch.", "tags": [ "batches" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "unassign_user_from_batch", "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": "\n\nList all carriers that have been added to this account.", "tags": [ "carriers" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "list_carriers", "parameters": [ { "$ref": "#/components/parameters/page_query_param" }, { "$ref": "#/components/parameters/page_size_query_param" }, { "name": "include_extended_details", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "example": false, "description": "When `true` (the default), each carrier in the response includes two additional arrays: `packages` (the package types supported by that carrier) and `options` (the carrier-level advanced options available for that carrier).\nSet to `false` to omit both arrays and reduce response payload size. This is useful when you only need basic carrier information such as `carrier_id`, `balance`, or `services`.\n" } ], "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": "\n\nRetrive details about a specific carrier by its carrier ID.", "tags": [ "carriers" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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" } } }, "delete": { "summary": "Disconnect carrier by ID", "description": "\n\nDisconnect a carrier from the account by its carrier ID.", "tags": [ "carriers" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "disconnect_carrier_by_id", "responses": { "204": { "description": "The request was successful.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/empty_response_body" } }, "application/json": { "schema": { "$ref": "#/components/schemas/empty_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/carriers/{carrier_id}/add_funds": { "x-visibility": "public", "summary": "Carrier funds", "description": "All carriers require that funds to be attached to an account to ensure payment for the various services they provide to their customers.", "parameters": [ { "$ref": "#/components/parameters/carrier_id_path_param" } ], "put": { "summary": "Add funds to carrier", "description": "\n\nAdd funds to a carrier account.", "tags": [ "carriers" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "add_funds_to_carrier", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/add_funds_to_carrier_request_body" } } } }, "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/add_funds_to_carrier_response_body" } } } }, "400": { "$ref": "#/components/responses/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": "\n\nGet a list of the options available for a specific carriers.", "tags": [ "carriers" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nList the package types associated with a specific carrier. This endpoint only returns carrier-provided package types, not custom package types.", "tags": [ "carriers" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nList the services associated with a specific carrier ID.", "tags": [ "carriers" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nDownload labels and other shipment-related documents.", "operationId": "download_file", "tags": [ "downloads" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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/documents/combined_labels": { "x-visibility": "public", "summary": "Created combined label document", "description": "Download a combined label file", "post": { "summary": "Created combined label document", "description": "\n\nDownload a combined label file", "tags": [ "labels" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "create_combined_label_document", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_combined_label_document_request_body" } } } }, "responses": { "200": { "description": "The requested object creation was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_combined_label_document_response_body" } } } }, "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": "\n\nRetrieve 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" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nCreate 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" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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/freight/provider_accounts": { "x-visibility": "public", "summary": "Freight provider accounts", "description": "List or connect freight provider accounts.\n", "get": { "summary": "List freight provider accounts", "description": "\n\nReturn the freight provider accounts connected to your account. Every freight request identifies the account it goes through with a `freight_provider_account_id`, so start here to find the ID to quote, book, and track with.\n\nOnly active connections are returned. An account with no freight provider connected receives an empty array.\n", "operationId": "list_freight_provider_accounts", "tags": [ "freight" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_freight_provider_accounts_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Connect a freight provider account", "description": "\n\nConnect a freight account the seller already holds with the provider. Both connectable providers — `speedship` (WWEX) and `unishippers` — authenticate with an OAuth client ID / secret pair issued by the provider.\n\nThe credentials are verified against the provider before they are stored, so a `201` means the connection can be quoted against immediately.\n\nA seller may hold one connection per provider. Connecting a provider that is already connected returns `409` with error code `freight_provider_already_connected` and the existing `freight_provider_account_id`. Use `PUT /v2/freight/provider_accounts/{freight_provider_account_id}/credentials` to rotate credentials on the existing connection. Use `DELETE /v2/freight/provider_accounts/{freight_provider_account_id}` to disconnect it.\n", "operationId": "connect_freight_provider_account", "tags": [ "freight" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connect_freight_provider_account_request_body" } } } }, "responses": { "201": { "description": "The freight provider account was connected successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/freight_provider_account" }, "example": { "freight_provider_account_id": "se-4821", "freight_provider_code": "SPEEDSHIP", "nickname": "My WWEX account" } } } }, "400": { "description": "A required field is missing or invalid, or the `freight_provider_code` is not a supported value.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" }, "example": { "request_id": "4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a", "errors": [ { "error_source": "shipengine", "error_type": "validation", "error_code": "field_value_required", "message": "client_id is required." } ] } } } }, "409": { "description": "The seller already has an active connection to this provider (`freight_provider_already_connected`). The error body includes the existing `freight_provider_account_id`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" }, "example": { "request_id": "4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a", "errors": [ { "error_source": "shipengine", "error_type": "business_rules", "error_code": "freight_provider_already_connected", "message": "This account is already connected to freight provider 'speedship' as se-4821. Replace the credentials on that freight provider account instead of connecting again." } ] } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/freight/provider_accounts/{freight_provider_account_id}": { "x-visibility": "public", "summary": "Freight provider account", "description": "Disconnect a freight provider account.", "parameters": [ { "name": "freight_provider_account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/se_id" }, "example": "se-4821", "description": "The identifier of the freight provider account to disconnect." } ], "delete": { "summary": "Disconnect a freight provider account", "description": "\n\nDisconnect a freight provider account, removing its stored credentials.\n\nThis is a soft delete: existing shipments and their tracking and documents are unaffected, but\nthe account can no longer be quoted or booked against until it is reconnected via\n`POST /v2/freight/provider_accounts`.\n", "operationId": "disconnect_freight_provider_account", "tags": [ "freight" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "responses": { "204": { "description": "The freight provider account was disconnected successfully." }, "404": { "description": "No active freight provider account with this `freight_provider_account_id` was found for this account.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" }, "example": { "request_id": "4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a", "errors": [ { "error_source": "shipengine", "error_type": "validation", "error_code": "invalid_identifier", "message": "freight_provider_account_id se-999 is invalid.", "field_name": "freight_provider_account_id" } ] } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/freight/provider_accounts/{freight_provider_account_id}/credentials": { "x-visibility": "public", "summary": "Freight provider account credentials", "description": "Replace the credentials stored for a freight provider account.", "parameters": [ { "name": "freight_provider_account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/se_id" }, "example": "se-4821", "description": "The identifier of the freight provider account whose credentials to replace." } ], "put": { "summary": "Update freight provider account credentials", "description": "\n\nReplace the credentials stored for a freight provider account — the mechanism for rotating a client secret without disconnecting.\n\nThe new credentials are verified against the provider before they replace the stored pair, so a failed verification leaves the existing connection working. The connection's nickname and account number are untouched.\n", "operationId": "update_freight_provider_account_credentials", "tags": [ "freight" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update_freight_provider_account_credentials_request_body" } } } }, "responses": { "200": { "description": "The credentials were replaced successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/freight_provider_account" }, "example": { "freight_provider_account_id": "se-4821", "freight_provider_code": "SPEEDSHIP", "nickname": "My WWEX account" } } } }, "400": { "description": "A required field is missing or invalid.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" }, "example": { "request_id": "4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a", "errors": [ { "error_source": "shipengine", "error_type": "validation", "error_code": "field_value_required", "message": "client_secret is required." } ] } } } }, "404": { "description": "No active freight provider account with this `freight_provider_account_id` was found for this account.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" }, "example": { "request_id": "4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a", "errors": [ { "error_source": "shipengine", "error_type": "validation", "error_code": "invalid_identifier", "message": "freight_provider_account_id se-999 is invalid.", "field_name": "freight_provider_account_id" } ] } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/freight/quotes": { "x-visibility": "public", "summary": "Freight quotes", "description": "Request less-than-truckload (LTL) freight rates from the carriers available through a freight provider connected to your account.\n", "post": { "summary": "Get freight quotes", "description": "\n\nRetrieve freight rate offers for a shipment. Each offer in the response is a bookable quote from a specific LTL carrier.\n\nThere are two ways to request quotes:\n\n- **Inline.** Describe the shipment in the request: `ship_from`, `ship_to`, and `handling_units`.\n- **Linked to an existing shipment.** Provide `shipment_id`. The origin is taken from the shipment's ship-from warehouse and the destination from the order's ship-to address, so `ship_from` must be omitted, and `ship_to` may contain only `location_type`. `handling_units`, `accessorials`, and `insurance` are optional in this mode: when provided they are saved as the shipment's freight configuration, and when omitted the previously saved configuration is reused. A `ship_to.location_type` you send is saved the same way.\n\nTo book one of the returned offers, pass its `offer_id` to [Book a freight shipment](#operation/book_freight_shipment).\n\nAll dimensions are interpreted as inches and all weights as pounds.\n", "operationId": "get_freight_quotes", "tags": [ "freight" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_freight_quotes_request_body" } } } }, "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/freight_quotes_response_body" } } } }, "400": { "description": "The request contained errors, the freight provider connection is not active for the account, or the provider could not return quotes.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" }, "example": { "request_id": "4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a", "errors": [ { "error_source": "shipengine", "error_type": "business_rules", "error_code": "unspecified", "message": "ship_from must not be provided when shipment_id is present" } ] } } } }, "404": { "description": "The `shipment_id` does not identify a shipment on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/freight/shipments": { "x-visibility": "public", "summary": "Freight shipments", "description": "Book freight offers returned by [Get freight quotes](#operation/get_freight_quotes) and list the freight shipments on your account.\n", "post": { "summary": "Book a freight shipment", "description": "\n\nBook one of the offers returned by [Get freight quotes](#operation/get_freight_quotes). Booking dispatches the shipment with the LTL carrier and generates the shipment's documents, such as the Bill of Lading.\n\nAs with quoting, there are two ways to book:\n\n- **Linked to an existing shipment.** Provide `shipment_id`. The shipment must already have a freight quote — call [Get freight quotes](#operation/get_freight_quotes) for it first. The origin, destination, and handling units all come from the shipment and its saved freight configuration, so `ship_from`, `ship_to`, and `handling_units` must be omitted.\n- **Inline.** Omit `shipment_id` and provide `ship_from`, `ship_to`, and `handling_units`. A shipment record is created for the booking and marked as shipped.\n\nPass the `offer_id` from the offer you are booking. The provider connection, carrier, and expiration are resolved server-side from the stored offer.\n", "operationId": "book_freight_shipment", "tags": [ "freight" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/book_freight_shipment_request_body" } } } }, "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/book_freight_shipment_response_body" } } } }, "400": { "description": "The request contained errors, the quote has expired, the freight provider connection is not active for the account, the linked shipment has no freight configuration or a cancelled one, or the provider rejected the booking.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" }, "example": { "request_id": "4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a", "errors": [ { "error_source": "shipengine", "error_type": "system", "error_code": "unspecified", "message": "The quote has expired. Please request a new quote." } ] } } } }, "404": { "description": "The `shipment_id` does not identify a shipment on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "summary": "List freight shipments", "description": "\n\nReturn the freight shipments on your account, most recently created first. Results are paginated.\n", "operationId": "list_freight_shipments", "tags": [ "freight" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 1, "default": 1 }, "example": 1, "description": "The page of results to return. Values below `1` are treated as `1`." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 500, "default": 25 }, "example": 50, "description": "The number of freight shipments to return per page. Values above `500` are capped at `500`." }, { "name": "created_at_start", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-09-01T00:00:00Z", "description": "Only return freight shipments created on or after this date and time, in ISO 8601 format. The start of the range is inclusive." }, { "name": "created_at_end", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-11-01T00:00:00Z", "description": "Only return freight shipments created before this date and time, in ISO 8601 format. The end of the range is exclusive." } ], "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_freight_shipments_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/freight/shipments/{freight_shipment_id}": { "x-visibility": "public", "summary": "Freight shipment", "description": "Retrieve or cancel an individual freight shipment.", "parameters": [ { "$ref": "#/components/parameters/freight_shipment_id_path_param" } ], "get": { "summary": "Get freight shipment by ID", "description": "\n\nRetrieve a single freight shipment, including its current status, carrier reference numbers, and the documents generated for it.\n", "operationId": "get_freight_shipment_by_id", "tags": [ "freight" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/freight_shipment_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "The freight shipment does not exist on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" }, "example": { "request_id": "4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a", "errors": [ { "error_source": "shipengine", "error_type": "business_rules", "error_code": "invalid_identifier", "message": "Invalid freight_shipment_id.", "field_name": "freight_shipment_id", "field_value": "se-98765432" } ] } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Cancel a freight shipment", "description": "\n\nCancel a booked freight shipment with the carrier. The response indicates whether the associated pickup was also cancelled.\n\nCancellation windows are set by the carrier. A shipment that has already been picked up usually cannot be cancelled, and the provider's rejection is returned as a `400 Bad Request`.\n", "operationId": "cancel_freight_shipment", "tags": [ "freight" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancel_freight_shipment_response_body" } } } }, "400": { "description": "The freight shipment ID is malformed, or the provider rejected the cancellation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" } } } }, "404": { "description": "The freight shipment does not exist on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/freight/shipments/{freight_shipment_id}/documents": { "x-visibility": "public", "summary": "Freight shipment documents", "description": "List the documents generated for a freight shipment.", "parameters": [ { "$ref": "#/components/parameters/freight_shipment_id_path_param" } ], "get": { "summary": "List freight shipment documents", "description": "\n\nList the documents available for a freight shipment, such as the Bill of Lading, pallet labels, and the proof of delivery. Documents become available as the shipment progresses: the Bill of Lading is generated at booking, while a proof of delivery only exists after delivery.\n\nEach document's `url` is a path on the API host that returns the PDF, for example `https://api.shipstation.com/v2/downloads/...`.\n", "operationId": "list_freight_shipment_documents", "tags": [ "freight" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_freight_shipment_documents_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "The freight shipment does not exist on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/freight/shipments/{freight_shipment_id}/tracking": { "x-visibility": "public", "summary": "Freight shipment tracking", "description": "Retrieve live tracking for a booked freight shipment.", "parameters": [ { "$ref": "#/components/parameters/freight_shipment_id_path_param" } ], "get": { "summary": "Get freight shipment tracking", "description": "\n\nRetrieve the current tracking status and event history for a booked freight shipment directly from the carrier.\n\nThe shipment is tracked by its PRO number when one has been assigned, and by its BOL number otherwise. A shipment that has neither returns a `400 Bad Request` with error code `freight_tracking_not_available` — this is normal immediately after booking, before the carrier assigns a PRO number.\n", "operationId": "get_freight_shipment_tracking", "tags": [ "freight" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/freight_shipment_tracking_response_body" } } } }, "400": { "description": "The freight shipment ID is malformed, the shipment has no PRO or BOL number to track yet (`freight_tracking_not_available`), or the freight provider connection is not active (`freight_connection_inactive`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" }, "example": { "request_id": "4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a", "errors": [ { "error_source": "shipengine", "error_type": "business_rules", "error_code": "freight_tracking_not_available", "message": "Tracking is not yet available for this shipment. A PRO or BOL number is required." } ] } } } }, "404": { "description": "The freight shipment does not exist on this account (`freight_shipment_not_found`), or the carrier returned no tracking information (`freight_tracking_not_found`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" }, "example": { "request_id": "4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a", "errors": [ { "error_source": "carrier", "error_type": "business_rules", "error_code": "freight_tracking_not_found", "message": "No tracking information was found for this shipment." } ] } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/freight/tracking": { "x-visibility": "public", "summary": "Freight tracking by number", "description": "Track any freight shipment by its PRO or BOL number.", "get": { "summary": "Get freight tracking by number", "description": "\n\nRetrieve tracking for a freight shipment by its PRO or BOL number, whether or not the shipment was booked through ShipStation. Use this when you have the carrier's reference number but no `freight_shipment_id` — for example, for a shipment booked outside the API.\n\n`carrier_scac` is required as well as the number itself, because the freight provider needs the SCAC to resolve a tracking number.\n", "operationId": "get_freight_tracking", "tags": [ "freight" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "parameters": [ { "name": "freight_provider_account_id", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/se_id" }, "example": "se-4821", "description": "The freight provider account to track through. Retrieve it with [List freight provider accounts](#operation/list_freight_provider_accounts).\n" }, { "name": "tracking_number", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 }, "example": "072-51293847", "description": "The PRO or BOL number to track." }, { "name": "tracking_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "pro_number", "bol_number" ] }, "example": "pro_number", "description": "Which kind of number `tracking_number` is." }, { "name": "carrier_scac", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 }, "example": "FXFE", "description": "The Standard Carrier Alpha Code (SCAC) of the LTL carrier. Required: the freight provider needs the SCAC to resolve a tracking number.\n" } ], "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/freight_tracking_response_body" } } } }, "400": { "description": "`freight_provider_account_id` is missing or is not a valid account ID (`freight_provider_id_required`), `tracking_number`, `tracking_type`, or `carrier_scac` is missing or invalid, or the freight provider connection is not active (`freight_connection_inactive`).\n\nThe `freight_provider_id_required` message still names the parameter `seller_freight_provider_id`, the name this parameter had previously. Match on `error_code`, not on `message`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" }, "example": { "request_id": "4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a", "errors": [ { "error_source": "shipengine", "error_type": "business_rules", "error_code": "freight_provider_id_required", "message": "seller_freight_provider_id is required." } ] } } } }, "404": { "description": "The carrier returned no tracking information for the number (`freight_tracking_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" } } } }, "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": "\n\nThis 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" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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/external_shipment_id_query_param", "description": "Only return labels for a specific external shipment ID." }, { "$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": "\n\nPurchase and print a label for shipment.", "tags": [ "labels" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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" }, "example": { "label_id": "se-2135218", "status": "completed", "shipment_id": "se-11310579", "ship_date": "2026-05-04T07:00:00Z", "delivery_prediction": { "delivery_date": "2026-05-06", "confidence_level": "high" }, "created_at": "2026-05-04T12:24:34.4153952Z", "shipment_cost": { "currency": "usd", "amount": 83.86 }, "insurance_cost": { "currency": "usd", "amount": 0 }, "requested_comparison_amount": { "currency": "usd", "amount": 0 }, "rate_details": [ { "rate_detail_type": "shipping", "carrier_description": "Shipping", "carrier_billing_code": "BaseServiceCharge", "carrier_memo": "", "amount": { "currency": "usd", "amount": 59.07 }, "billing_source": "carrier" }, { "rate_detail_type": "additional_fees", "carrier_description": "Surge Fee", "carrier_billing_code": "434", "carrier_memo": "", "amount": { "currency": "usd", "amount": 0.96 }, "billing_source": "carrier" }, { "rate_detail_type": "prepaid_duties", "carrier_description": "Duties and Taxes (Guaranteed)", "carrier_billing_code": "", "carrier_memo": "", "amount": { "currency": "usd", "amount": 0 }, "billing_source": "dutiestax" }, { "rate_detail_type": "prepaid_taxes", "carrier_description": "Duties and Taxes (Guaranteed)", "carrier_billing_code": "", "carrier_memo": "", "amount": { "currency": "usd", "amount": 13.43 }, "billing_source": "dutiestax" }, { "rate_detail_type": "prepaid_import_fees", "carrier_description": "Duties and Taxes (Guaranteed)", "carrier_billing_code": "", "carrier_memo": "", "amount": { "currency": "usd", "amount": 10.4 }, "billing_source": "dutiestax" } ], "tracking_number": "1Z2A863C6620022614", "is_return_label": false, "rma_number": "RMA-2026-0001", "is_international": true, "batch_id": "se-0", "carrier_id": "se-440144", "charge_event": "carrier_default", "service_code": "ups_worldwide_express", "package_code": "package", "voided": false, "voided_at": "2026-05-04T12:24:34.4153952Z", "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK", "label_format": "pdf", "display_scheme": "label", "label_layout": "4x6", "trackable": true, "carrier_code": "ups", "tracking_status": "in_transit", "label_download": { "href": "https://api.shipstation.com/v2/downloads/label-2135218.pdf", "pdf": "https://api.shipstation.com/v2/downloads/label-2135218.pdf", "png": "https://api.shipstation.com/v2/downloads/label-2135218.png", "zpl": "https://api.shipstation.com/v2/downloads/label-2135218.zpl" }, "form_download": { "href": "https://api.shipstation.com/v2/downloads/form-2135218.pdf" }, "paperless_download": { "href": "https://api.shipstation.com/v2/downloads/paperless-2135218", "instructions": "any instructions", "handoff_code": "1234" }, "insurance_claim": { "href": "https://api.shipstation.com/v2/insurance/claims/se-2135218" }, "packages": [] } } } }, "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": "\n\nWhen 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" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nPurchase a label using a shipment ID that has already been created with the desired address and package info.\n", "tags": [ "labels" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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 or custom rate shopper configuration, then purchase\na label.\n\n**Standard strategies** (`cheapest`, `fastest`, `best_value`): The Rate\nShopper analyzes available rates across your connected carriers and selects\nthe best option according to the chosen strategy.\n\n**Custom rate shoppers** (service collection GUID): Uses your configured\nservice collection to determine which carrier/service combinations are\neligible, applies transit time filtering (with separate domestic/international\nthresholds), and selects the cheapest qualifying rate. This feature requires\nan Advanced plan. Free plan can only use the default standard strategies.\n", "parameters": [ { "$ref": "#/components/parameters/rate_shopper_id_path_param" } ], "post": { "summary": "Purchase label with rate shopper", "description": "\n\nCreate a label using Rate Shopper to automatically select the best\ncarrier and service based on the specified strategy or custom rate\nshopper configuration.\n\nYou can use a standard strategy (`cheapest`, `fastest`, `best_value`)\nor pass a custom rate shopper ID (service collection GUID) to use your\nown configured service collection for rate selection.\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" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": { "description": "Bad Request. Possible causes:\n- Request body is missing\n- `rate_shopper_id` is not a valid standard strategy or GUID\n- Custom rate shopper not found (invalid GUID or not owned by seller)\n- Custom rate shopper is not active\n- No rates available for the shipment\n- Unable to resolve carrier and service using the specified custom rate shopper\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/labels/shipping_rules/{shipping_rule_id}": { "x-visibility": "public", "summary": "Purchase label using a shipping rule", "description": "Purchase and print a label using a Shipping Rule to automatically select\ncarrier and service based on the configured rule.\n", "parameters": [ { "name": "shipping_rule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/se_id" }, "description": "Shipping Rule ID" } ], "post": { "summary": "Purchase label with shipping rule", "description": "\n\nPurchase and print a shipping label using a Shipping Rule. The Shipping Rule automatically selects the optimal carrier and service based on the rule's configuration.\n\n**Dynamic Ordering**: Service Group Rules can now use dynamic ordering (_Cheapest_ or _Fastest_) to automatically rank eligible services in real time based on live rate or transit data. This feature is currently available for US sellers with USA domestic carrier services only. For more details, see the [Configuring \"Order Services By\" guide](/apis/@shipstation-v2/docs/shipping/shipping-rules-configuring-order-services-by.md).\n\nThe request body must NOT include `carrier_id`, `service_code`, or `shipping_rule_id` in the shipment object. If any of these fields are provided, the API will return a `400 Bad Request` error.\n\n> **Important:** While calls to this endpoint from ShipStation native accounts will not fail with a 401 Unauthorized or 402 Payment Required error, Shipping Rules are not available to ShipStation accounts, preventing successful use of this endpoint. This endpoint may only be used by ShipStation API (formerly ShipEngine) accounts.\n", "tags": [ "labels" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "create_label_from_shipping_rule", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_label_from_shipping_rule_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/{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": "\n\nRetrieve a specific label by its label ID.", "tags": [ "labels" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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/external_shipment_id/{external_shipment_id}": { "x-visibility": "public", "summary": "Get label by external shipment ID", "description": "Find a label using the external shipment id", "parameters": [ { "name": "external_shipment_id", "in": "path", "schema": { "type": "string" }, "required": true, "example": "0bcb569d-1727-4ff9-ab49-b2fec0cee5ae" } ], "get": { "summary": "Get label by external shipment ID", "description": "\n\nFind a label by using the external shipment id that was used during label creation.\n\n> **Warning:** This endpoint returns only the first label found with the specified `external_shipment_id`. If multiple labels share the same `external_shipment_id`, only the earliest created label will be returned. To retrieve all labels with a specific `external_shipment_id`, use the [list labels endpoint](#operation/list_labels) with the `external_shipment_id` query parameter.\n", "tags": [ "labels" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "get_label_by_external_shipment_id", "parameters": [ { "name": "label_download_type", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/label_download_type" }, "example": "url" } ], "responses": { "200": { "description": "The requested label was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_label_by_external_shipment_id_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "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": "\n\nCreate 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" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nRetrieve the label's tracking details.", "tags": [ "labels" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nVoid 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" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nCancel 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" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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/labels/{label_id}/documents": { "x-visibility": "public", "summary": "Carrier documents for a label", "description": "Register, list, and manage carrier documents (such as commercial invoices and certificates of origin) for a purchased label. Carrier details are resolved automatically from the label.\n\n> **Note:** Carrier Document Upload is currently supported for **UPS** and **FedEx** only. Accepted document types and file size vary by carrier — please refer to the [Carrier Document Upload guide](/upload-carrier-documents) for the full list.\n", "parameters": [ { "$ref": "#/components/parameters/label_id_path_param" } ], "post": { "summary": "Register a document for a label", "description": "\n\nRegister a carrier document against a label. The response returns an `upload` target; upload the document file to that target, then call the [send documents](#operation/send_label_documents) endpoint to transmit it to the carrier. Carrier information is resolved automatically from the label.\n", "tags": [ "documents" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "operationId": "register_label_document", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/register_document_request_body" } } } }, "responses": { "200": { "description": "The document was registered successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/register_document_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "summary": "List documents for a label", "description": "\n\nRetrieve the carrier documents registered against a label, including their processing status.", "tags": [ "documents" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "operationId": "list_label_documents", "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_documents_response_body" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/labels/{label_id}/documents/{document_id}": { "x-visibility": "public", "summary": "A carrier document for a label", "parameters": [ { "$ref": "#/components/parameters/label_id_path_param" }, { "$ref": "#/components/parameters/document_id_path_param" } ], "delete": { "summary": "Delete a label document", "description": "\n\nDelete a carrier document registered against a label. Documents that have already been sent to the carrier cannot be deleted.", "tags": [ "documents" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "operationId": "delete_label_document", "responses": { "204": { "description": "The document was deleted successfully." }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The document cannot be deleted in its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/labels/{label_id}/documents/send": { "x-visibility": "public", "summary": "Send a label's documents to the carrier", "parameters": [ { "$ref": "#/components/parameters/label_id_path_param" } ], "post": { "summary": "Send label documents", "description": "\n\nTransmit all uploaded documents for a label to the carrier. Documents must be uploaded to their `upload` target before they can be sent.", "tags": [ "documents" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "operationId": "send_label_documents", "responses": { "200": { "description": "The documents were sent to the carrier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/send_documents_response_body" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "The document service is temporarily unavailable. Try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" } } } } } } }, "/v2/documents/{document_id}/download": { "x-visibility": "public", "summary": "Download a carrier document", "parameters": [ { "$ref": "#/components/parameters/document_id_path_param" } ], "get": { "summary": "Download a document", "description": "\n\nDownload the file for a previously registered carrier document.", "tags": [ "documents" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "operationId": "download_document", "responses": { "200": { "description": "The document file.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "description": "The document is invalid and cannot be downloaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" } } } }, "425": { "description": "The document is still being processed. Try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "The document service is temporarily unavailable. Try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" } } } } } } }, "/v2/mailing/netstamps": { "x-visibility": "public", "summary": "Create NetStamps", "description": "Create NetStamps (individual stamps with row/column positioning) for USPS.\n", "post": { "summary": "Create netstamps", "description": "\n\nCreate one or more NetStamps. Each shipment in the request produces an individual stamp\nwith optional row/column positioning via `advanced_options.netstamps_options`.\n", "tags": [ "mailing" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "create_netstamps", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_netstamps_labels_request_body" } } } }, "responses": { "200": { "description": "The labels were created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/multi_label_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/mailing/mail_labels": { "x-visibility": "public", "summary": "Create mailing labels", "description": "Create mailing labels on label sheets (e.g., SDC-3110) with start row/column positioning.\n", "post": { "summary": "Create mailing labels", "description": "\n\nCreate one or more mailing labels on a sheet layout.\nUse `mailing_options` to control which row and column to start printing from.\n", "tags": [ "mailing" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "create_mailing_labels", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_mail_labels_request_body" } } } }, "responses": { "200": { "description": "The labels were created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/multi_label_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/mailing/envelopes": { "x-visibility": "public", "summary": "Create envelope", "description": "Create a single envelope for USPS.\n", "post": { "summary": "Create envelope", "description": "\n\nCreate a single envelope shipment.\n", "tags": [ "mailing" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "create_envelope", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_envelope_label_request_body" } } } }, "responses": { "200": { "description": "The label was created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_label_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "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": "\n\nSimilar 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" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nEach 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" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nGet Manifest By Id", "tags": [ "manifests" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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/manifests/requests/{manifest_request_id}": { "x-visibility": "public", "summary": "Manifest request ID", "description": "Manifest Request ID", "parameters": [ { "$ref": "#/components/parameters/manifest_request_id_path_param" } ], "get": { "summary": "Get manifest request by ID", "description": "\n\nGet Manifest Request By Id", "tags": [ "manifests" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "get_manifest_request_by_id", "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_manifest_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "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": "\n\nList the custom package types associated with the account", "tags": [ "package_types" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nCreate a custom package type to better assist in getting accurate rate estimates", "tags": [ "package_types" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nGet Custom Package Type by ID", "tags": [ "package_types" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nUpdate the custom package type object by ID", "tags": [ "package_types" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nDelete a custom package using the ID", "tags": [ "package_types" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nList all pickups that have been scheduled for this carrier", "tags": [ "package_pickups" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nSchedule a package pickup with a carrier", "tags": [ "package_pickups" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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_success_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": "\n\nGet Pickup By ID", "tags": [ "package_pickups" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nDelete a previously-scheduled pickup by ID", "tags": [ "package_pickups" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nRetrieve a paginated list of purchase orders with optional filtering by status, warehouse, dates, and other criteria.\n", "tags": [ "purchase_orders" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nCreate a new purchase order with products from a supplier.\n", "tags": [ "purchase_orders" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nRetrieve detailed information about a specific purchase order including all products.\n", "tags": [ "purchase_orders" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nUpdate 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" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nUpdate 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" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nUpdate the status of a purchase order. Valid status transitions must be followed.\n", "tags": [ "purchase_orders" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nRecord receipt of products from a purchase order. This updates inventory levels\nand may automatically change purchase order status.\n", "tags": [ "purchase_orders" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nDownload a PDF document containing the purchase order summary.\nAvailable for purchase orders with status: open, receiving, received, or closed.\n", "tags": [ "purchase_orders" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nDownload a PDF document containing the received products summary.\nAvailable for purchase orders with status: receiving, received, or closed.\n", "tags": [ "purchase_orders" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nIt'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" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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" }, "example": { "rate_response": { "rates": [ { "rate_id": "se-7766853", "rate_type": "shipment", "carrier_id": "se-426451", "zone": 5, "package_type": "package", "shipping_amount": { "currency": "usd", "amount": 59.07 }, "insurance_amount": { "currency": "usd", "amount": 0 }, "confirmation_amount": { "currency": "usd", "amount": 0 }, "other_amount": { "currency": "usd", "amount": 20.63 }, "rate_details": [ { "rate_detail_type": "shipping", "carrier_description": "Shipping", "carrier_billing_code": "BaseServiceCharge", "carrier_memo": "", "amount": { "currency": "usd", "amount": 59.07 }, "billing_source": "Carrier" }, { "rate_detail_type": "additional_fees", "carrier_description": "Surge Fee", "carrier_billing_code": "434", "carrier_memo": "", "amount": { "currency": "usd", "amount": 0.96 }, "billing_source": "Carrier" }, { "rate_detail_type": "estimated_duties", "carrier_description": "Duties and Taxes (Estimated)", "carrier_billing_code": "", "carrier_memo": "", "amount": { "currency": "usd", "amount": 0 }, "billing_source": "DutiesTax" }, { "rate_detail_type": "estimated_taxes", "carrier_description": "Duties and Taxes (Estimated)", "carrier_billing_code": "", "carrier_memo": "", "amount": { "currency": "usd", "amount": 13.43 }, "billing_source": "DutiesTax" }, { "rate_detail_type": "estimated_import_fees", "carrier_description": "Duties and Taxes (Estimated)", "carrier_billing_code": "", "carrier_memo": "", "amount": { "currency": "usd", "amount": 6.24 }, "billing_source": "DutiesTax" } ], "delivery_days": 1, "guaranteed_service": true, "estimated_delivery_date": "2026-05-26T12:00:00Z", "carrier_delivery_days": "Tuesday 5/26 by 12:00 PM", "delivery_prediction": { "delivery_date": "2026-05-26", "confidence_level": "high" }, "ship_date": "2026-05-22T00:00:00Z", "negotiated_rate": false, "service_type": "UPS Worldwide Express®", "service_code": "ups_worldwide_express", "trackable": true, "carrier_code": "ups", "carrier_nickname": "UPS by ShipStation (USD)", "carrier_friendly_name": "UPS", "validation_status": "valid", "warning_messages": [], "error_messages": [] } ], "invalid_rates": [], "rate_request_id": "se-1224263", "shipment_id": "se-11501596", "status": "completed", "errors": [] }, "shipment_id": "se-11501596", "ship_date": "2026-05-22T00:00:00Z", "created_at": "2026-05-22T23:19:47.493Z", "modified_at": "2026-05-22T23:19:47.087Z", "shipment_status": "pending" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/rates/bulk": { "x-visibility": "public", "summary": "Bulk rates", "description": "Get specific rates for large groups of shipments", "post": { "summary": "Get bulk rates", "description": "\n\nGet Bulk Shipment Rates", "tags": [ "rates" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "compare_bulk_rates", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/compare_bulk_rates_request_body" } } } }, "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/compare_bulk_rates_response_body" } } } }, "400": { "$ref": "#/components/responses/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": "\n\nGet Rate Estimates", "tags": [ "rates" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nRetrieve a previously queried rate by its ID", "tags": [ "rates" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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/rate_shoppers": { "x-visibility": "public", "summary": "Rate Shoppers", "description": "Manage rate shoppers. Rate shoppers define a set of carrier services\nand rules used to automatically select the best rate when purchasing labels.\nThis includes both default rate shoppers (cheapest, fastest, best_value)\nand custom rate shoppers configured by the seller.\n", "get": { "summary": "List rate shoppers", "description": "\n\nRetrieve rate shoppers for the authenticated seller. By default this\nreturns both the default rate shoppers (cheapest, fastest, best_value)\nand any custom rate shoppers. Use the `type` parameter to filter.\n", "tags": [ "rate_shoppers" ], "x-plan": [ "ss-api-advanced_and_enterprise_plans", "ss-api-free_plan", "ss-standard_and_premium_plans" ], "operationId": "list_rate_shoppers", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "custom" ] }, "description": "Filter rate shoppers by type. When set to `custom`, only\nseller-created rate shoppers are returned (excludes defaults).\nWhen omitted, both default and custom rate shoppers are returned.\n" }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "name", "created_at" ], "default": "name" }, "description": "Field to sort results by. Sorting only applies to custom rate\nshoppers; default rate shoppers are always listed first.\n" }, { "name": "sort_dir", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort direction." } ], "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rate_shopper_list_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/rate_shoppers/{rate_shopper_id}": { "x-visibility": "public", "summary": "Rate Shopper", "description": "Get an individual rate shopper by ID or strategy name.", "parameters": [ { "name": "rate_shopper_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The rate shopper identifier. Can be one of:\n\n**Default rate shoppers (strategy name):**\n- `cheapest`: Lowest cost option\n- `fastest`: Fastest option at the lowest price\n- `best_value`: Lowest cost option arriving within 4 days\n\n**Custom rate shoppers:**\nA UUID (e.g., `f47ac10b-58cc-4372-a567-0e02b2c3d479`) identifying\na seller-created rate shopper.\n", "examples": { "default_strategy": { "value": "cheapest", "summary": "Default rate shopper using the cheapest strategy" }, "custom_uuid": { "value": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "summary": "Custom rate shopper by UUID" } } } ], "get": { "summary": "Get rate shopper by ID", "description": "\n\nRetrieve a single rate shopper by its identifier. Accepts both\ndefault strategy names (`cheapest`, `fastest`, `best_value`) and\ncustom rate shopper UUIDs.\n", "tags": [ "rate_shoppers" ], "x-plan": [ "ss-api-advanced_and_enterprise_plans", "ss-api-free_plan", "ss-standard_and_premium_plans" ], "operationId": "get_rate_shopper_by_id", "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rate_shopper_response" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/service_points/list": { "x-visibility": "public", "summary": "Service points", "post": { "summary": "List service points", "description": "\n\nList carrier service points by location", "operationId": "service_points_list", "tags": [ "service_points" ], "x-plan": [ "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_service_points_request" } } } }, "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_service_points_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/service_points/{carrier_code}/{country_code}/{service_point_id}": { "x-visibility": "public", "summary": "Service points", "parameters": [ { "name": "carrier_code", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "example": "stamps_com", "description": "Carrier code" }, { "name": "country_code", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "example": "CA", "description": "A two-letter [ISO 3166-1 country code](https://en.wikipedia.org/wiki/ISO_3166-1)" }, { "name": "service_point_id", "in": "path", "schema": { "type": "string" }, "required": true, "example": "614940" } ], "get": { "summary": "Get service point by ID", "description": "\n\nReturns a carrier service point by using the service_point_id", "operationId": "service_points_get_by_id", "tags": [ "service_points" ], "x-plan": [ "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_service_point_by_id_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "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": "\n\nGet list of Shipments", "tags": [ "shipments" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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/tag_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": "\n\nCreate one or more shipments", "tags": [ "shipments" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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/user": { "x-visibility": "public", "summary": "Assign user to shipments", "description": "Assign a user to one or more shipments", "post": { "summary": "Assign user to shipments", "description": "\n\nAssigns a user to one or more shipments. You can assign a single user\nto up to 500 shipments at once.\n", "tags": [ "shipments" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "assign_user_to_shipments", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/assign_user_request_body" } } } }, "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/assign_user_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/shipments/hold": { "x-visibility": "public", "summary": "Hold shipments", "description": "Hold one or more shipments until a given date", "post": { "summary": "Hold shipments", "description": "\n\nHolds one or more shipments until a given date. A shipment on hold has the\n`on_hold` status, and you can't purchase a label for it while it's on hold. On the\n`hold_until_date`, the shipment is released automatically and returns to the\n`pending` status. You can hold up to 500 shipments at once.\n\n`hold_until_date` is a date-only value: any time component you send is ignored, and\nthe date must be later than today.\n\nShipments that cannot be held — because they are not found, are cancelled, or have a\npurchased label — are reported in `errors`, and the remaining shipments are still held.\nIf only some of the shipments were held, the response status is `207`. If none of them\ncould be held, the response status is `404` when at least one shipment was not found,\nor `400` otherwise, and `shipment_ids` is empty.\n\nTo hold a single shipment, use [Hold a shipment](#operation/hold_shipment).\n", "tags": [ "shipments" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "hold_shipments", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/hold_shipments_request_body" } } } }, "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/hold_shipments_response_body" } } } }, "207": { "description": "The request was a partial success. Some shipments were not held; see `errors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/hold_shipments_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/shipments/restore": { "x-visibility": "public", "summary": "Restore shipments", "description": "Restore one or more shipments that are on hold", "post": { "summary": "Restore shipments", "description": "\n\nRestores one or more shipments that are on hold. Each restored shipment returns to\nthe `pending` status and its `hold_until_date` is cleared. You can restore up to\n500 shipments at once.\n\nShipments that cannot be restored — because they are not found or are not on hold —\nare reported in `errors`, and the remaining shipments are still restored. If only some\nof the shipments were restored, the response status is `207`. If none of them could be\nrestored, the response status is `404` when at least one shipment was not found, or\n`400` otherwise, and `shipment_ids` is empty.\n\nTo restore a single shipment, use [Restore a shipment](#operation/restore_shipment).\n", "tags": [ "shipments" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "restore_shipments", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/restore_shipments_request_body" } } } }, "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/restore_shipments_response_body" } } } }, "207": { "description": "The request was a partial success. Some shipments were not restored; see `errors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/restore_shipments_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "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": "\n\nQuery Shipments created using your own custom ID convention using this endpoint", "tags": [ "shipments" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nGet an individual shipment based on its ID", "tags": [ "shipments" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nUpdate 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, total_weight, and batch_ids.\n", "tags": [ "shipments" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nMark 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" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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}/hold": { "x-visibility": "public", "summary": "Hold shipment", "description": "Hold a shipment until a given date", "parameters": [ { "$ref": "#/components/parameters/shipment_id_path_param" } ], "put": { "summary": "Hold a shipment", "description": "\n\nHolds a shipment until a given date. A shipment on hold has the `on_hold` status,\nand you can't purchase a label for it while it's on hold. On the `hold_until_date`,\nthe shipment is released automatically and returns to the `pending` status. Holding\na shipment that is already on hold replaces the existing `hold_until_date`.\n\nA cancelled shipment or a shipment with a purchased label cannot be held and returns\na `400` response.\n\n`hold_until_date` is a date-only value: any time component you send is ignored, and\nthe date must be later than today.\n\nTo hold up to 500 shipments in one request, use [Hold shipments](#operation/hold_shipments).\n", "tags": [ "shipments" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "hold_shipment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/hold_shipment_request_body" } } } }, "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/hold_shipment_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/shipments/{shipment_id}/restore": { "x-visibility": "public", "summary": "Restore shipment", "description": "Restore a shipment that is on hold", "parameters": [ { "$ref": "#/components/parameters/shipment_id_path_param" } ], "put": { "summary": "Restore a shipment", "description": "\n\nRestores a shipment that is on hold. The shipment returns to the `pending` status and\nits `hold_until_date` is cleared. No request body is required.\n\nThe shipment must currently be on hold. Restoring a shipment in any other status\nreturns a `400` response.\n\nTo restore up to 500 shipments in one request, use [Restore shipments](#operation/restore_shipments).\n", "tags": [ "shipments" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "restore_shipment", "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/restore_shipment_response_body" } } } }, "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": "\n\nGet Rates for the shipment information associated with the shipment ID", "tags": [ "shipments" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": { "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" } ], "get": { "summary": "Get shipment tags", "description": "\n\nGet Shipment tags based on its ID", "tags": [ "shipments" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "shipments_list_tags", "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tag_shipment_response_body" } } } }, "400": { "$ref": "#/components/responses/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": "\n\nAdd a tag to the shipment object", "tags": [ "shipments" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nRemove an existing tag from the Shipment object", "tags": [ "shipments" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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/shipments/{shipment_id}/internal_notes": { "x-visibility": "public", "summary": "Shipment Internal Notes", "description": "Manage internal notes on a shipment. Internal notes are private seller-facing\nnotes that are not visible to the buyer.\n", "parameters": [ { "$ref": "#/components/parameters/shipment_id_path_param" } ], "post": { "summary": "Update internal notes for a shipment", "description": "\n\nUpdate the internal notes on a shipment. You can either overwrite the existing\nnotes entirely or append new text to the current notes.\n\n| Mode | `note` value | Result |\n|------|-------------|--------|\n| `overwrite` | `\"new note\"` | Replaces existing notes |\n| `overwrite` | `\"\"` or `\" \"` | Clears the note |\n| `append` | `\"new note\"` | Appends text to existing notes |\n", "tags": [ "shipments" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "update_shipment_internal_notes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "note", "mode" ], "properties": { "note": { "type": "string", "description": "The note text to set or append.", "example": "Customer called — prefers delivery after 5 PM" }, "mode": { "type": "string", "enum": [ "append", "overwrite" ], "description": "Controls how the note is applied.\n- `append` adds the text to the end of any existing notes.\n- `overwrite` replaces the existing notes entirely (use an empty string to clear).\n", "example": "append" } } } } } }, "responses": { "200": { "description": "The internal notes were updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "internal_notes": { "type": "string", "description": "The resulting internal notes after the update.", "example": "Original note\nCustomer called — prefers delivery after 5 PM" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/shipments/{shipment_id}/split": { "x-visibility": "public", "summary": "Split shipment", "description": "Split a shipment by moving some of its items into one or more new shipments.\n", "parameters": [ { "$ref": "#/components/parameters/shipment_id_path_param" } ], "post": { "summary": "Split a shipment", "description": "\n\nMove items from a shipment into one or more new shipments. Each entry in `shipments` creates one new\nshipment holding the items and quantities listed for it. Items and quantities that you don't list\nstay on the original shipment.\n\nEach new shipment is based on the original shipment and stays linked to the same sales order, so\nthe order source keeps getting shipment notifications after the split.\n\nTo split a shipment:\n\n- It must have a `shipment_status` of `pending`, `awaiting_payment`, or `on_hold`.\n- It must be linked to a sales order. Check `sales_order_ids` on the shipment.\n- It can't come from a marketplace that supplies its own shipping labels.\n- All of the items you move must belong to the same sales order. To move items from more than one\n sales order, make one request for each sales order.\n- At least one item must stay on the original shipment.\n\nGet the `item_id` values from the `items` array of the shipment, using\n[Get shipment by id](#operation/get_shipment_by_id).\n", "tags": [ "shipments" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "split_shipment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/split_shipment_request_body" }, "examples": { "one_new_shipment": { "summary": "Move one unit of an item into a new shipment", "value": { "shipments": [ { "items": [ { "item_id": "1402291169813", "quantity": 1 } ] } ] } }, "two_new_shipments": { "summary": "Create two new shipments", "value": { "shipments": [ { "items": [ { "item_id": "1402291169813", "quantity": 2 } ] }, { "items": [ { "item_id": "1402291169814", "quantity": 1 }, { "item_id": "1402291169815", "quantity": 1 } ] } ] } } } } } }, "responses": { "200": { "description": "The shipment was split.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/split_shipment_response_body" }, "example": { "shipment_id": "se-202902255", "new_shipment_ids": [ "se-202902301" ] } } } }, "400": { "description": "The request contained errors, or the shipment can't be split. The `error_code` identifies the reason:\n\n| `error_code` | Reason |\n|---|---|\n| `invalid_field_value` | A value in the request can't be used. For example, a quantity is larger than the quantity on the shipment, an item is listed twice in the same new shipment, or no items would stay on the original shipment. |\n| `invalid_identifier` | An `item_id` isn't on the shipment. |\n| `invalid_status` | The shipment has already shipped, has been cancelled, or is in another status that can't be split. |\n| `sales_order_link_required` | The shipment isn't linked to a sales order. |\n| `multiple_sales_orders` | The items you're moving belong to more than one sales order. |\n| `bring_your_own_label_not_supported` | The shipment comes from a marketplace that supplies its own shipping labels. |\n| `unspecified` | The split was rejected for another reason. The `message` explains why. |\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" }, "examples": { "quantity_too_large": { "summary": "Quantity is larger than the quantity on the shipment", "value": { "request_id": "4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a", "errors": [ { "error_source": "shipengine", "error_type": "validation", "error_code": "invalid_field_value", "message": "Cannot move 3 of item 1402291169813; the shipment only has 2.", "field_name": "quantity" } ] } }, "multiple_sales_orders": { "summary": "Items belong to more than one sales order", "value": { "request_id": "4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a", "errors": [ { "error_source": "shipengine", "error_type": "business_rules", "error_code": "multiple_sales_orders", "message": "The items being split out belong to more than one sales order. Split items from one sales order at a time." } ] } }, "invalid_status": { "summary": "Shipment has already shipped", "value": { "request_id": "4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a", "errors": [ { "error_source": "shipengine", "error_type": "business_rules", "error_code": "invalid_status", "message": "Shipment se-202902255 cannot be changed because it has already shipped or been cancelled.", "field_name": "shipment_id", "field_value": "se-202902255" } ] } } } } } }, "404": { "description": "The `shipment_id` does not identify a shipment on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/shipments/{shipment_id}/merge": { "x-visibility": "public", "summary": "Merge shipments", "description": "Merge other shipments into a shipment.\n", "parameters": [ { "$ref": "#/components/parameters/shipment_id_path_param" } ], "post": { "summary": "Merge shipments", "description": "\n\nMerge one or more shipments into the shipment in the URL. The items from each shipment in\n`shipment_ids` move onto the shipment in the URL, and the shipments in `shipment_ids` are then\ndeleted.\n\nThe shipment in the URL stays linked to its own sales orders and becomes linked to the sales orders\nof every shipment merged into it, so order sources keep getting shipment notifications. The merged\nshipments can belong to different sales orders.\n\nTo merge shipments:\n\n- Every shipment, including the one in the URL, must have a `shipment_status` of `pending`,\n `awaiting_payment`, or `on_hold`.\n- Every shipment must be linked to a sales order. Check `sales_order_ids` on each shipment.\n- None of the shipments can come from a marketplace that supplies its own shipping labels.\n\nIf `shipment_ids` includes the shipment in the URL or lists a shipment more than once, the extra\nentries are ignored.\n", "tags": [ "shipments" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "merge_shipments", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merge_shipments_request_body" }, "example": { "shipment_ids": [ "se-202902301", "se-202902302" ] } } } }, "responses": { "200": { "description": "The shipments were merged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merge_shipments_response_body" }, "example": { "shipment_id": "se-202902255", "merged_shipment_ids": [ "se-202902301", "se-202902302" ] } } } }, "400": { "description": "The request contained errors, or the shipments can't be merged. The `error_code` identifies the reason:\n\n| `error_code` | Reason |\n|---|---|\n| `invalid_field_value` | A value in the request can't be used. For example, `shipment_ids` contains only the shipment in the URL, or contains `null`. |\n| `invalid_status` | One of the shipments has already shipped, has been cancelled, or is in another status that can't be merged. |\n| `sales_order_link_required` | One of the shipments isn't linked to a sales order. |\n| `bring_your_own_label_not_supported` | One of the shipments comes from a marketplace that supplies its own shipping labels. |\n| `unspecified` | The merge was rejected for another reason. The `message` explains why. |\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" }, "examples": { "nothing_to_merge": { "summary": "No shipment other than the target was provided", "value": { "request_id": "4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a", "errors": [ { "error_source": "shipengine", "error_type": "validation", "error_code": "invalid_field_value", "message": "At least one shipment other than the target shipment is required to merge.", "field_name": "shipment_ids" } ] } }, "sales_order_link_required": { "summary": "A shipment isn't linked to a sales order", "value": { "request_id": "4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a", "errors": [ { "error_source": "shipengine", "error_type": "business_rules", "error_code": "sales_order_link_required", "message": "Shipment se-202902302 is not linked to a sales order, so it cannot be merged.", "field_name": "shipment_id", "field_value": "se-202902302" } ] } } } } } }, "404": { "description": "The shipment in the URL, or one of the shipments in `shipment_ids`, does not identify a shipment on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/shipments/{shipment_id}/documents": { "x-visibility": "public", "summary": "Carrier documents for a shipment", "description": "Register, list, and manage carrier documents (such as commercial invoices and certificates of origin) for a shipment.\n\n> **Note:** Carrier Document Upload is currently supported for **UPS** and **FedEx** only. Accepted document types and file size vary by carrier — please refer to the [Carrier Document Upload guide](/upload-carrier-documents) for the full list.\n", "parameters": [ { "$ref": "#/components/parameters/shipment_id_path_param" } ], "post": { "summary": "Register a document for a shipment", "description": "\n\nRegister a carrier document against a shipment. The response returns an `upload` target; upload the document file to that target so it can later be sent to the carrier.\n", "tags": [ "documents" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "operationId": "register_shipment_document", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/register_document_request_body" } } } }, "responses": { "200": { "description": "The document was registered successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/register_document_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "summary": "List documents for a shipment", "description": "\n\nRetrieve the carrier documents registered against a shipment, including their processing status.", "tags": [ "documents" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "operationId": "list_shipment_documents", "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_documents_response_body" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/shipments/{shipment_id}/documents/{document_id}": { "x-visibility": "public", "summary": "A carrier document for a shipment", "parameters": [ { "$ref": "#/components/parameters/shipment_id_path_param" }, { "$ref": "#/components/parameters/document_id_path_param" } ], "delete": { "summary": "Delete a shipment document", "description": "\n\nDelete a carrier document registered against a shipment. Documents that have already been sent to the carrier cannot be deleted.", "tags": [ "documents" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "operationId": "delete_shipment_document", "responses": { "204": { "description": "The document was deleted successfully." }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The document cannot be deleted in its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_response_body" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/shipments/{shipment_id}/labels": { "x-visibility": "public", "summary": "Shipments and their document statuses", "description": "Retrieve the shipments associated with the given id, each with its tracking number and the carrier documents registered against it.\n", "parameters": [ { "$ref": "#/components/parameters/shipment_id_path_param" } ], "get": { "summary": "List shipments and their document statuses", "description": "\n\nRetrieve each shipment associated with the given id, including its tracking number and registered carrier documents.", "tags": [ "documents" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "operationId": "list_shipment_label_documents", "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_shipment_labels_response_body" } } } }, "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": "\n\nRetrieve a paginated list of all suppliers with optional filtering by supplier name.\n", "tags": [ "suppliers" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nCreate a new supplier with contact and address information.\n", "tags": [ "suppliers" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nRetrieve detailed information about a specific supplier.\n", "tags": [ "suppliers" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nUpdate an existing supplier's information.\n", "tags": [ "suppliers" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nGet a list of all tags associated with an account.", "tags": [ "tags" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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" } } }, "post": { "summary": "Create a new tag", "description": "\n\nCreate a new tag for customizing how you track your shipments.", "tags": [ "tags" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "create_tag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_tag_request_body" } } } }, "responses": { "200": { "description": "The requested object creation 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/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": "\n\nCreate a new Tag for customizing how you track your shipments", "tags": [ "tags" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "create_tag_by_name", "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" } } }, "delete": { "summary": "Delete tag", "description": "\n\nDelete a tag that is no longer needed", "tags": [ "tags" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "delete_tag", "responses": { "204": { "description": "The request was successful.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/empty_response_body" } }, "application/json": { "schema": { "$ref": "#/components/schemas/empty_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/tags/{tag_name}/{new_tag_name}": { "x-visibility": "public", "summary": "Tag", "description": "Update tag name", "parameters": [ { "$ref": "#/components/parameters/tag_name_path_param" }, { "name": "new_tag_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tag_name" } } ], "put": { "summary": "Update tag name", "description": "\n\nChange a tag name while still keeping the relevant shipments attached to it", "tags": [ "tags" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "rename_tag", "responses": { "204": { "description": "The request was successful.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/empty_response_body" } }, "application/json": { "schema": { "$ref": "#/components/schemas/empty_response_body" } } } }, "400": { "$ref": "#/components/responses/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": "\n\nGet all totes for the seller, optionally filtered by warehouse.", "tags": [ "totes" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nCreate multiple totes at once. Returns both successfully created totes and any failures.", "tags": [ "totes" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nGet the number of totes in each warehouse.", "tags": [ "totes" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nRetrieve details of a specific tote.", "tags": [ "totes" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nUpdate the name or barcode of an existing tote.", "tags": [ "totes" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nDelete a tote by its ID.", "tags": [ "totes" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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/tokens/ephemeral": { "x-visibility": "public", "post": { "summary": "Get ephemeral token", "description": "\n\nThis endpoint returns a token that can be passed to an application for authorized access. The lifetime of this token is 10 seconds.", "operationId": "tokens_get_ephemeral_token", "parameters": [ { "name": "redirect", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/redirect" }, "description": "Include a redirect url to the application formatted with the ephemeral token." } ], "tags": [ "tokens" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tokens_get_ephemeral_token_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/tracking": { "x-visibility": "public", "summary": "Tracking a package", "description": "If you generate your labels through ShipStation, then you can subscribe to real-time tracking events for free!", "get": { "summary": "Get tracking information", "description": "\n\nRetrieve package tracking information", "tags": [ "tracking" ], "x-plan": [ "ss-api-advanced_and_enterprise_plans" ], "operationId": "get_tracking_log", "parameters": [ { "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." }, { "name": "tracking_number", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 }, "example": "9405511899223197428490", "description": "The tracking number associated with a shipment" }, { "name": "carrier_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/se_id" }, "description": "Carrier ID" } ], "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_tracking_log_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/tracking/start": { "x-visibility": "public", "summary": "Start tracking a package", "description": "Allows you to subscribe to tracking updates for a package. You specify the carrier_code and tracking_number of the package, and receive notifications via webhooks whenever the shipping status changes.", "post": { "summary": "Start tracking a package", "description": "\n\nAllows you to subscribe to tracking updates for a package. You specify the carrier_code and tracking_number of the package, and receive notifications via webhooks whenever the shipping status changes.", "tags": [ "tracking" ], "x-plan": [ "ss-api-advanced_and_enterprise_plans" ], "operationId": "start_tracking", "parameters": [ { "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." }, { "name": "tracking_number", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 }, "example": "9405511899223197428490", "description": "The tracking number associated with a shipment" }, { "name": "carrier_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/se_id" }, "description": "Carrier ID" } ], "responses": { "204": { "description": "The request was successful.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/empty_response_body" } }, "application/json": { "schema": { "$ref": "#/components/schemas/empty_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/tracking/stop": { "x-visibility": "public", "summary": "Stop tracking a package", "description": "Unsubscribe from tracking updates for a package.", "post": { "summary": "Stop tracking a package", "description": "\n\nUnsubscribe from tracking updates for a package.", "tags": [ "tracking" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nRetrieve a list of warehouses associated with this account.", "tags": [ "warehouses" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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" } } }, "post": { "summary": "Create warehouse", "description": "\n\nCreate a warehouse location that you can use to create shipping items by simply passing in the generated warehouse id. If the return address is not supplied in the request body then it is assumed that the origin address is the return address as well", "tags": [ "warehouses" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "create_warehouse", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_warehouse_request_body" } } } }, "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_warehouse_response_body" } } } }, "400": { "$ref": "#/components/responses/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": "\n\nRetrieve warehouse data based on the warehouse ID", "tags": [ "warehouses" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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" } } }, "put": { "summary": "Update warehouse by ID", "description": "\n\nUpdate Warehouse object information", "tags": [ "warehouses" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "update_warehouse", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update_warehouse_request_body" } } } }, "responses": { "204": { "description": "The request was successful.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/empty_response_body" } }, "application/json": { "schema": { "$ref": "#/components/schemas/empty_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete warehouse by ID", "description": "\n\nDelete a warehouse by ID", "tags": [ "warehouses" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "delete_warehouse", "responses": { "204": { "description": "The request was successful.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/empty_response_body" } }, "application/json": { "schema": { "$ref": "#/components/schemas/empty_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/warehouses/{warehouse_id}/settings": { "x-visibility": "public", "summary": "Warehouse settings", "description": "Warehouse settings", "parameters": [ { "$ref": "#/components/parameters/warehouse_id_path_param" } ], "put": { "summary": "Update warehouse settings", "description": "\n\nUpdate Warehouse settings object information", "tags": [ "warehouses" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "update_warehouse_settings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update_warehouse_settings_request_body" } } } }, "responses": { "204": { "description": "The request was successful.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/empty_response_body" } }, "application/json": { "schema": { "$ref": "#/components/schemas/empty_response_body" } } } }, "400": { "$ref": "#/components/responses/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": "\n\nList all webhooks currently enabled for the account.", "tags": [ "webhooks" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nCreate a webhook for specific events in the environment.", "tags": [ "webhooks" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nRetrieve individual webhook by an ID", "tags": [ "webhooks" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nUpdate the webhook url property", "tags": [ "webhooks" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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": "\n\nDelete a webhook", "tags": [ "webhooks" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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", "description": "\n\nLists the users of your ShipStation account, with optional filters such as `status`.", "tags": [ "users" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "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", "description": "\n\nLists the products in your ShipStation account. Filter by `sku`, `name` or `active` status, and paginate with `page` and `page_size`.", "tags": [ "products" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-advanced_and_enterprise_plans" ], "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": { "$ref": "#/components/schemas/product" } }, "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" } } } }, "/v2/products/{product_id}": { "x-visibility": "public", "summary": "Product", "description": "Retrieve a single product by its unique identifier.\n", "parameters": [ { "name": "product_id", "in": "path", "required": true, "description": "Unique identifier for the product", "schema": { "type": "integer" }, "example": 10736794 } ], "get": { "operationId": "getProduct", "summary": "Get product", "description": "\n\nRetrieves a single product by its `product_id`.", "tags": [ "products" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-advanced_and_enterprise_plans" ], "responses": { "200": { "description": "The product was retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/product" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/products/create": { "x-visibility": "public", "summary": "Create products", "description": "Create one or more products in your ShipStation account.\n", "post": { "operationId": "createProducts", "summary": "Create products", "description": "\n\nCreates one or more products in your ShipStation account.", "tags": [ "products" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-advanced_and_enterprise_plans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "products" ], "properties": { "products": { "type": "array", "description": "Array of products to create", "items": { "type": "object", "required": [ "sku", "name" ], "properties": { "sku": { "type": "string", "description": "Stock Keeping Unit identifier. Must be unique within your account.", "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" }, "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", "null" ], "description": "Whether customs is required", "example": null }, "tags": { "type": [ "array", "null" ], "description": "Tags to assign. Only `tag_id` is used on write; `name` and `color` are response-only fields returned when reading a product.", "items": { "type": "object", "properties": { "tag_id": { "type": "integer", "example": 21121 } } } }, "aliases": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "store_id": { "type": "integer", "example": 2095811 }, "sku_alias": { "type": "string", "example": "alt-sku" } } } }, "is_returnable": { "type": [ "boolean", "null" ], "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": false }, "auto_split_option": { "type": [ "string", "null" ], "description": "Auto split option", "example": "do_not_split" }, "auto_split_custom_quantity": { "type": [ "integer", "null" ], "description": "Auto split custom quantity when auto_split_option is set to custom_quantity", "example": 3 } } } } } } } } }, "responses": { "200": { "description": "The products were created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "created_product_ids": { "type": "array", "description": "IDs of the newly created products", "items": { "type": "integer" }, "example": [ 10736794 ] }, "request_id": { "type": "string", "description": "Unique identifier for this request", "example": "35e75c12-cb26-4d58-9fa1-b0047480acc1" }, "errors": { "type": "array", "description": "Any errors that occurred during creation", "items": { "type": "object", "properties": { "error_source": { "type": "string", "example": "shipstation" }, "error_type": { "type": "string", "example": "validation" }, "error_code": { "type": "string", "example": "field_value_required" }, "message": { "type": "string", "example": "sku is required." }, "field_name": { "type": "string", "example": "sku" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/products/update": { "x-visibility": "public", "summary": "Update product", "description": "Update an existing product. The full product object is required — partial updates are not supported.\n", "post": { "operationId": "updateProducts", "summary": "Update product", "description": "\n\nUpdates an existing product. The full product object is required, as partial updates are not supported.", "tags": [ "products" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-advanced_and_enterprise_plans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "products" ], "properties": { "products": { "type": "array", "description": "Array of products to update. Each product requires the full object — partial updates are not supported.", "items": { "type": "object", "required": [ "product_id", "sku", "name" ], "properties": { "product_id": { "type": "integer", "description": "Unique identifier for the product to update", "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" }, "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", "null" ], "description": "Whether customs is required", "example": null }, "tags": { "type": [ "array", "null" ], "description": "Tags to assign. Only `tag_id` is used on write; `name` and `color` are response-only fields returned when reading a product.", "items": { "type": "object", "properties": { "tag_id": { "type": "integer", "example": 21121 } } } }, "aliases": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "store_id": { "type": "integer", "example": 2095811 }, "sku_alias": { "type": "string", "example": "alt-sku" } } } }, "is_returnable": { "type": [ "boolean", "null" ], "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": false }, "auto_split_option": { "type": [ "string", "null" ], "description": "Auto split option", "example": "do_not_split" }, "auto_split_custom_quantity": { "type": [ "integer", "null" ], "description": "Auto split custom quantity when auto_split_option is set to custom_quantity", "example": 3 } } } } } } } } }, "responses": { "200": { "description": "The products were updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "updated_products": { "type": "array", "description": "The updated product objects", "items": { "$ref": "#/components/schemas/product" } }, "request_id": { "type": "string", "description": "Unique identifier for this request", "example": "7f3b8288-7e46-4c12-a96a-fe7f42fd9e0a" }, "errors": { "type": "array", "description": "Any errors that occurred during the update", "items": { "type": "object", "properties": { "error_source": { "type": "string", "example": "shipstation" }, "error_type": { "type": "string", "example": "validation" }, "error_code": { "type": "string", "example": "field_value_required" }, "message": { "type": "string", "example": "product_id is required." }, "field_name": { "type": "string", "example": "product_id" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/products/deactivate": { "x-visibility": "public", "summary": "Deactivate products", "description": "Deactivate one or more products. Deactivated products are no longer active but are not permanently deleted.\n", "post": { "operationId": "deactivateProducts", "summary": "Deactivate products", "description": "\n\nDeactivates one or more products. Deactivated products are no longer active but are not permanently deleted.", "tags": [ "products" ], "x-plan": [ "ss-standard_and_premium_plans", "ss-api-advanced_and_enterprise_plans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product_ids" ], "properties": { "product_ids": { "type": "array", "description": "Array of product IDs to deactivate", "items": { "type": "integer" }, "example": [ 10736794, 10736795 ] } } } } } }, "responses": { "200": { "description": "The products were deactivated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "deactivated_product_ids": { "type": "array", "description": "IDs of the products that were deactivated", "items": { "type": "integer" }, "example": [ 10736794, 10736795 ] }, "request_id": { "type": "string", "description": "Unique identifier for this request", "example": "1e051b3d-8753-4192-b415-4a0926fe0b00" }, "errors": { "type": "array", "description": "Any errors that occurred during deactivation", "items": { "type": "object", "properties": { "error_source": { "type": "string", "example": "shipstation" }, "error_type": { "type": "string", "example": "validation" }, "error_code": { "type": "string", "example": "field_value_required" }, "message": { "type": "string", "example": "product_ids is required." }, "field_name": { "type": "string", "example": "product_ids" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/account/settings": { "summary": "Account settings", "description": "ShipStation API account settings", "get": { "summary": "List account settings", "description": "\n\nList all account settings for the ShipStation API account", "tags": [ "account" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "list_account_settings", "responses": { "200": { "description": "The request was a success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "default_label_layout": { "type": "string", "enum": [ "4x6", "Letter" ], "description": "The default label layout", "example": "4x6" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/account/settings/images": { "summary": "Account settings images", "description": "ShipStation API account images", "get": { "summary": "List account images", "description": "\n\nList all account images for the ShipStation API account", "tags": [ "account" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "list_account_images", "responses": { "200": { "description": "The request was a success", "content": { "application/json": { "schema": { "type": "object", "required": [ "images" ], "additionalProperties": false, "properties": { "images": { "type": "array", "readOnly": true, "minItems": 0, "items": { "type": "object", "description": "A ShipStation API account images body", "additionalProperties": false, "properties": { "label_image_id": { "type": "string", "readOnly": true, "description": "A string that uniquely identifies the image", "example": "img_123abc" }, "name": { "type": "string", "minLength": 1, "maxLength": 50, "example": "My logo", "description": "A human readable name for the image" }, "is_default": { "type": "boolean", "example": false, "description": "Indicates whether this image is set as default" }, "image_content_type": { "type": "string", "enum": [ "image/png", "image/jpeg" ], "example": "image/png", "description": "The file type of the image" }, "image_data": { "type": "string", "description": "A base64 encoded string representation of the image", "example": "iVBORw0KGgoAAAANSUhEUgAAABkAAAAZCAYAAADE6YVj..." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "The date and time that the image was created in ShipStation API", "example": "2024-01-15T10:30:00Z" }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "The date and time that the image was modified in ShipStation API", "example": "2024-01-15T10:30:00Z" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Create an account image", "description": "\n\nCreate an account image", "tags": [ "account" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "create_account_image", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "A ShipStation API account settings images request body", "required": [ "name", "image_content_type", "image_data" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50, "example": "My logo", "description": "A human readable name for the image" }, "is_default": { "type": "boolean", "example": false, "description": "Indicates whether this image is set as default" }, "image_content_type": { "type": "string", "enum": [ "image/png", "image/jpeg" ], "example": "image/png", "description": "The file type of the image" }, "image_data": { "type": "string", "example": "iVBORw0KGgoAAAANSUhEUgAAABkAAAAZCAYAAADE6YVj...", "description": "A base64 encoded string representation of the image" } } } } } }, "responses": { "200": { "description": "The requested object creation was a success", "content": { "application/json": { "schema": { "type": "object", "description": "A ShipStation API account images body", "additionalProperties": false, "properties": { "label_image_id": { "type": "string", "readOnly": true, "description": "A string that uniquely identifies the image", "example": "img_123abc" }, "name": { "type": "string", "minLength": 1, "maxLength": 50, "example": "My logo", "description": "A human readable name for the image" }, "is_default": { "type": "boolean", "example": false, "description": "Indicates whether this image is set as default" }, "image_content_type": { "type": "string", "enum": [ "image/png", "image/jpeg" ], "example": "image/png", "description": "The file type of the image" }, "image_data": { "type": "string", "example": "iVBORw0KGgoAAAANSUhEUgAAABkAAAAZCAYAAADE6YVj...", "description": "A base64 encoded string representation of the image" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "example": "2024-01-15T10:30:00Z", "description": "The date and time that the image was created in ShipStation API" }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true, "example": "2024-01-15T10:30:00Z", "description": "The date and time that the image was modified in ShipStation API" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/account/settings/images/{label_image_id}": { "summary": "Account settings images", "description": "ShipStation API account images", "get": { "summary": "Get account image by ID", "description": "\n\nRetrieve information for an account image", "tags": [ "account" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "get_account_settings_images_by_id", "parameters": [ { "name": "label_image_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Label Image Id", "example": "img_123abc" } ], "responses": { "200": { "description": "The request was a success", "content": { "application/json": { "schema": { "type": "object", "description": "A ShipStation API account images body", "additionalProperties": false, "properties": { "label_image_id": { "type": "string", "readOnly": true, "description": "A string that uniquely identifies the image", "example": "img_123abc" }, "name": { "type": "string", "minLength": 1, "maxLength": 50, "example": "My logo", "description": "A human readable name for the image" }, "is_default": { "type": "boolean", "example": false, "description": "Indicates whether this image is set as default" }, "image_content_type": { "type": "string", "enum": [ "image/png", "image/jpeg" ], "example": "image/png", "description": "The file type of the image" }, "image_data": { "type": "string", "example": "iVBORw0KGgoAAAANSUhEUgAAABkAAAAZCAYAAADE6YVj...", "description": "A base64 encoded string representation of the image" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "example": "2024-01-15T10:30:00Z", "description": "The date and time that the image was created in ShipStation API" }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true, "example": "2024-01-15T10:30:00Z", "description": "The date and time that the image was modified in ShipStation API" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "summary": "Update account image by ID", "description": "\n\nUpdate information for an account image", "tags": [ "account" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "update_account_settings_images_by_id", "parameters": [ { "name": "label_image_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Label Image Id", "example": "img_123abc" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "A ShipStation API account settings images request body", "required": [ "is_default" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50, "example": "My logo", "description": "A human readable name for the image" }, "is_default": { "type": "boolean", "example": false, "description": "Indicates whether this image is set as default" }, "image_content_type": { "type": "string", "enum": [ "image/png", "image/jpeg" ], "example": "image/png", "description": "The file type of the image" }, "image_data": { "type": "string", "example": "iVBORw0KGgoAAAANSUhEUgAAABkAAAAZCAYAAADE6YVj...", "description": "A base64 encoded string representation of the image" } } } } } }, "responses": { "204": { "description": "The request was successful", "content": { "text/plain": { "schema": { "type": "string", "minLength": 0, "maxLength": 0 } }, "application/json": { "schema": { "type": "string", "minLength": 0, "maxLength": 0 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete account image by ID", "description": "\n\nDelete account image by ID", "tags": [ "account" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans" ], "operationId": "delete_account_image_by_id", "parameters": [ { "name": "label_image_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Label Image Id", "example": "img_123abc" } ], "responses": { "204": { "description": "The request was successful", "content": { "text/plain": { "schema": { "type": "string", "minLength": 0, "maxLength": 0 } }, "application/json": { "schema": { "type": "string", "minLength": 0, "maxLength": 0 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/connections/carriers/{carrier_name}": { "summary": "Carrier connections", "description": "Carrier connections", "parameters": [ { "name": "carrier_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/carrier_name" }, "example": "dhl_express", "description": "The carrier name, such as `stamps_com`, `ups`, `fedex`, or `dhl_express`." } ], "post": { "summary": "Connect a carrier account", "description": "\n\nConnect a carrier account", "tags": [ "connections" ], "x-plan": [ "ss-api-advanced_and_enterprise_plans" ], "operationId": "connect_carrier", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connect_carrier_request_body" } } } }, "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connect_carrier_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/connections/carriers/{carrier_name}/{carrier_id}": { "summary": "Disconnect a carrier", "description": "Disconnect a carrier", "parameters": [ { "name": "carrier_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/carrier_name" }, "example": "dhl_express", "description": "The carrier name, such as `stamps_com`, `ups`, `fedex`, or `dhl_express`." }, { "name": "carrier_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/se_id" }, "example": "se-28529731", "description": "Carrier ID" } ], "delete": { "summary": "Disconnect a carrier", "description": "\n\nDisconnect a carrier", "tags": [ "connections" ], "x-plan": [ "ss-api-advanced_and_enterprise_plans" ], "operationId": "disconnect_carrier", "responses": { "204": { "description": "The request was successful.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/empty_response_body" } }, "application/json": { "schema": { "$ref": "#/components/schemas/empty_response_body" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/connections/carriers/{carrier_name}/{carrier_id}/settings": { "summary": "Carrier settings", "description": "Carrier settings", "parameters": [ { "name": "carrier_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/carrier_name_with_settings" }, "example": "dhl_express", "description": "The carrier name, such as `ups`, `fedex`, or `dhl_express`." }, { "name": "carrier_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/se_id" }, "example": "se-28529731", "description": "Carrier ID" } ], "get": { "summary": "Get carrier settings", "description": "\n\nGet carrier settings", "tags": [ "connections" ], "x-plan": [ "ss-api-advanced_and_enterprise_plans" ], "operationId": "get_carrier_settings", "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_carrier_settings_response_body" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "summary": "Update carrier settings", "description": "\n\nUpdate carrier settings", "tags": [ "connections" ], "x-plan": [ "ss-api-advanced_and_enterprise_plans" ], "operationId": "update_carrier_settings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update_carrier_settings_request_body" } } } }, "responses": { "204": { "description": "The request was successful.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/empty_response_body" } }, "application/json": { "schema": { "$ref": "#/components/schemas/empty_response_body" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/addresses/validate": { "summary": "Address validation", "description": "Address validation ensures accurate addresses and can lead to reduced shipping costs by preventing address correction surcharges.\nShipStation API cross references multiple databases to validate addresses and identify potential deliverability issues.\n", "post": { "summary": "Validate an address", "description": "\n\nAddress validation ensures accurate addresses and can lead to reduced shipping costs by preventing address correction surcharges.\nShipStation API cross references multiple databases to validate addresses and identify potential deliverability issues.\n", "tags": [ "addresses" ], "x-plan": [ "ss-api-advanced_and_enterprise_plans" ], "operationId": "validate_address", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/validate_address_request_body" }, "examples": { "all_known_fields_request": { "summary": "All known fields", "description": "A call that returns a status of `verified`.", "value": [ { "name": "Mickey and Minnie Mouse", "phone": "714-781-4565", "company_name": "The Walt Disney Company", "address_line1": "500 South Buena Vista Street", "city_locality": "Burbank", "state_province": "CA", "postal_code": "91521", "country_code": "US" } ] } } } } }, "responses": { "200": { "description": "The request was a success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/validate_address_response_body" }, "examples": { "all_known_fields": { "summary": "All known fields", "description": "A response for a `verified` status call.", "value": [ { "status": "verified", "original_address": { "name": "Mickey and Minnie Mouse", "phone": "714-781-4565", "company_name": "The Walt Disney Company", "address_line1": "500 South Buena Vista Street", "address_line2": null, "address_line3": null, "city_locality": "Burbank", "state_province": "CA", "postal_code": "91521", "country_code": "US", "address_residential_indicator": "unknown" }, "matched_address": { "name": "MICKEY AND MINNIE MOUSE", "phone": "714-781-4565", "company_name": "THE WALT DISNEY COMPANY", "address_line1": "500 S BUENA VISTA ST", "address_line2": null, "address_line3": null, "city_locality": "BURBANK", "state_province": "CA", "postal_code": "91521-0007", "country_code": "US", "address_residential_indicator": "no" }, "messages": [] } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/checkout_rates": { "x-visibility": "public", "summary": "Checkout rates configurations", "description": "Create a checkout rates configuration or list the configurations on your account. A configuration groups the delivery options a buyer can choose from at checkout for a single storefront.\n", "post": { "operationId": "create_checkout_rates_config", "summary": "Create a checkout rates configuration", "description": "\n\nCreate a checkout rates configuration together with its initial delivery options and shared settings. The configuration is returned with a generated `config_id` and, for each option, a generated `option_id`.\n\nFor `live_rate` and `local_delivery` options, each service's `carrier_id` and `service_code` are validated and resolved against the carriers connected to your account.\n", "tags": [ "checkout_rates" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_checkout_rates_config_request_body" }, "example": { "options": [ { "name": "Standard Shipping", "type": "live_rate", "services": [ { "carrier_id": "se-1234567", "service_code": "usps_priority_mail" } ], "fee_mode": "add", "fee_percentage": 10, "fallback_mode": "flat_rate", "fallback_rate_amount": 5, "fallback_rate_currency": "USD" }, { "name": "Free Shipping", "type": "free" }, { "name": "Flat Rate Shipping", "type": "flat_rate", "amount": 4.99, "currency": "USD" } ], "shared_settings": { "calculation_method": "by_volume", "dimensions_by_weight": [ { "max_weight": { "value": 10, "unit": "pound" }, "default_dimensions": { "length": 12, "width": 9, "height": 6, "unit": "inch" } } ] } } } } }, "responses": { "201": { "description": "The checkout rates configuration was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checkout_rates_config_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "list_checkout_rates_configs", "summary": "List checkout rates configurations", "description": "\n\nReturn a summary of every checkout rates configuration on your account. Each entry contains identifying fields only; use [Get a checkout rates configuration](#operation/get_checkout_rates_config) to retrieve an individual configuration's options and shared settings.\n", "tags": [ "checkout_rates" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "responses": { "200": { "description": "The list of checkout rates configurations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_checkout_rates_configs_response_body" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/checkout_rates/{config_id}": { "x-visibility": "public", "summary": "A checkout rates configuration", "parameters": [ { "name": "config_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "description": "The unique identifier of the checkout rates configuration." } ], "get": { "operationId": "get_checkout_rates_config", "summary": "Get a checkout rates configuration", "description": "\n\nRetrieve a single checkout rates configuration, including all of its delivery options and shared settings.\n", "tags": [ "checkout_rates" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "responses": { "200": { "description": "The requested checkout rates configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checkout_rates_config_response_body" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/checkout_rates/{config_id}/options": { "x-visibility": "public", "summary": "Delivery options for a checkout rates configuration", "parameters": [ { "name": "config_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "description": "The unique identifier of the checkout rates configuration." } ], "post": { "operationId": "add_checkout_rates_option", "summary": "Add a delivery option", "description": "\n\nAdd a delivery option to an existing checkout rates configuration. Option names must be unique within a configuration; adding an option whose name already exists returns a `409 Conflict`.\n", "tags": [ "checkout_rates" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checkout_rates_option_request_body" } } } }, "responses": { "201": { "description": "The delivery option was added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checkout_rates_option_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/checkout_rates/{config_id}/options/{option_id}": { "x-visibility": "public", "summary": "A delivery option", "parameters": [ { "name": "config_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "description": "The unique identifier of the checkout rates configuration." }, { "name": "option_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 100001, "description": "The unique identifier of the delivery option." } ], "get": { "operationId": "get_checkout_rates_option", "summary": "Get a delivery option", "description": "\n\nRetrieve a single delivery option belonging to a checkout rates configuration.\n", "tags": [ "checkout_rates" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "responses": { "200": { "description": "The requested delivery option.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checkout_rates_option_response_body" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "update_checkout_rates_option", "summary": "Update a delivery option", "description": "\n\nReplace the configuration of an existing delivery option. Option names must remain unique within a configuration; renaming an option to a name already in use returns a `409 Conflict`.\n", "tags": [ "checkout_rates" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checkout_rates_option_request_body" } } } }, "responses": { "200": { "description": "The delivery option was updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checkout_rates_option_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "delete_checkout_rates_option", "summary": "Delete a delivery option", "description": "\n\nMarks a delivery option as inactive (`is_active: false`) instead of removing it; it still appears in the configuration.\n", "tags": [ "checkout_rates" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "responses": { "204": { "$ref": "#/components/responses/NoContent" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/checkout_rates/{config_id}/quotes": { "x-visibility": "public", "summary": "Checkout rate quotes", "parameters": [ { "name": "config_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "description": "The unique identifier of the checkout rates configuration to quote against." } ], "post": { "operationId": "calculate_checkout_rates", "summary": "Calculate checkout rates", "description": "\n\nCalculate the shipping rates a buyer should see at checkout for the given destination and cart, using the delivery options defined on the configuration. The response contains one rate per delivery option that produced a price, and each rate carries its own `quote_id` that can be retrieved later with [Get a checkout rate quote](#operation/get_checkout_rates_quote).\n", "tags": [ "checkout_rates" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/calculate_checkout_rates_request_body" }, "example": { "ship_to": { "address_type": "residential", "address_line1": "525 S Winchester Blvd", "city_locality": "San Jose", "state_province": "CA", "postal_code": "95128", "country_code": "US" }, "items": [ { "name": "T-Shirt", "quantity": 2, "price": 19.99, "weight": { "value": 8, "unit": "ounce" }, "dimensions": { "length": 10, "width": 8, "height": 1, "unit": "inch" } } ], "currency": "USD" } } } }, "responses": { "200": { "description": "The calculated rates for the cart.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/calculate_checkout_rates_response_body" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/checkout_rates/quotes/{quote_id}": { "x-visibility": "public", "summary": "A checkout rate quote", "parameters": [ { "name": "quote_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "description": "The unique identifier of a previously calculated rate quote." } ], "get": { "operationId": "get_checkout_rates_quote", "summary": "Get a checkout rate quote", "description": "\n\nRetrieve a previously calculated rate quote, including the destination it was calculated for and the rates that were returned.\n\n> **Note:** Quotes are retained for a limited time. A request for an expired or unknown `quote_id` returns `404 Not Found`.\n", "tags": [ "checkout_rates" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "responses": { "200": { "description": "The requested rate quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checkout_rates_quote_response_body" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/delivery_predictions": { "x-visibility": "public", "summary": "Delivery predictions", "post": { "operationId": "create_delivery_predictions", "summary": "Predict delivery dates", "description": "\n\nPredict delivery dates for one or more carrier and service combinations on a single lane, using ShipStation's delivery prediction model rather than the estimate quoted by the carrier.\n\nThe prediction stands on its own: this endpoint does not price the shipment, create a shipment or a label, and nothing it returns is stored. Send the origin and destination once and list every carrier and service combination you want predicted for that lane.\n\nA requested combination comes back as an entry in `delivery_predictions` or as an entry in `warnings`, never both. A combination the model has no coverage for becomes a warning, so a response where nothing is supported is still a `200` with an empty `delivery_predictions` array. A combination the model returns nothing usable for is in neither array. Combinations are matched by `carrier_code` and `service_code` rather than by position, and are returned as the model reports them rather than echoed back.\n\nThere is no limit you need to manage on your side: a request with more combinations than the model accepts in one call is split across several calls automatically, and none are dropped.\n", "tags": [ "delivery_predictions" ], "x-plan": [ "ss-api-free_plan", "ss-api-advanced_and_enterprise_plans", "ss-standard_and_premium_plans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/delivery_predictions_request_body" }, "example": { "from_country_code": "US", "from_postal_code": "78701", "to_country_code": "US", "to_postal_code": "90210", "ship_date": "2026-07-01", "delivery_options": [ { "carrier_details": { "carrier_code": "ups", "service_code": "ups_ground" } }, { "carrier_details": { "carrier_code": "fedex", "service_code": "fedex_express_saver" } } ] } } } }, "responses": { "200": { "description": "The predictions for the requested lane, and a warning for every combination that could not be predicted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/delivery_predictions_response_body" }, "example": { "delivery_predictions": [ { "ship_date": "2026-07-01", "delivery_date": "2026-07-04", "confidence_level": "high", "carrier_details": { "carrier_code": "ups", "service_code": "ups_ground" } } ], "warnings": [ { "carrier_details": { "carrier_code": "fedex", "service_code": "fedex_express_saver" }, "message": "Carrier and service combination is unsupported." } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "tags": [ { "name": "account", "description": "Manage account settings, including label image preferences and configurations.\n", "x-displayName": "Account" }, { "name": "addresses", "description": "Validate shipping addresses to ensure accuracy and improve delivery success rates.\n", "x-displayName": "Addresses" }, { "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": "checkout_rates", "description": "Configure the shipping options your buyers see at checkout and calculate live shipping rates for a cart.\n\nA **checkout rates configuration** groups one or more **delivery options** (for example, `live_rate`, `flat_rate`, `free`, or `local_delivery`) under a single storefront. Once a configuration exists, call the quotes endpoint to return the rates a buyer should see for a given destination and cart.\n\nThis feature proxies to the Delivery Options service and translates external identifiers (`carrier_id`, `service_code`) to the account's connected carriers and services automatically.\n", "x-displayName": "Checkout Rates" }, { "name": "connections", "description": "Manage carrier connections, including adding new carriers, updating settings, and managing payment information.\n", "x-displayName": "Connections" }, { "name": "delivery_predictions", "description": "Predict delivery dates for carrier and service combinations on a lane, using ShipStation's delivery prediction model instead of the estimate quoted by the carrier.\n", "x-displayName": "Delivery Predictions" }, { "name": "documents", "description": "Document Upload lets you submit self-prepared customs paperwork — such as Pro Forma Invoices, USMCA forms (for example, the USMCA Certification of Origin), and other supporting documents — directly to the carrier. Use it whenever a shipment requires supplemental international documentation, helping to prevent customs delays and delivery issues.\n\nDocuments can be provided at either the **shipment level** or the **label level** — that is, before or after a label is generated:\n\n- **Shipment level (before a label exists).** Register the document with [Register a document for a shipment](#operation/register_shipment_document). Documents registered at the shipment level are forwarded to the carrier automatically.\n- **Label level (after a label is generated).** Register the document with [Register a document for a label](#operation/register_label_document), then call [Send label documents](#operation/send_label_documents) to transmit it to the carrier.\n\nTo enable document upload for a shipment or label, set the `pending_documents` flag on the shipment's `customs` object.\n\nSS API: You can also suppress a carrier-generated document by setting the `suppress_carrier_generated_documents` [advanced option](/advanced-options) on the shipment. Currently, only the commercial invoice is supported, and only for UPS.\n\nCarrier Document Upload is currently supported for **UPS** and **FedEx** only. Accepted document types and file size vary by carrier — see the [Carrier Document Upload guide](/upload-carrier-documents) for the full list.\n\nFor **step-by-step instructions on uploading documents through the ShipStation API dashboard**, see the [Customs Declarations: Document Upload help article](https://help.shipstation.com/hc/en-us/articles/50888603341211). This is useful for operations teams who need to upload documents manually or as a fallback if API integration issues occur.\n", "x-displayName": "Documents" }, { "name": "downloads", "description": "Download your label files in PDF, PNG, and ZPL.\n", "x-displayName": "Downloads" }, { "name": "freight", "description": "Quote, book, track, and manage less-than-truckload (LTL) freight shipments through a freight provider connected to your account.\n", "x-displayName": "Freight" }, { "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": "mailing", "description": "Create mailing labels for USPS including NetStamps, mail labels and envelopes.\n", "x-displayName": "Mailing" }, { "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": "rate_shoppers", "description": "Manage rate shoppers. Rate shoppers define carrier service collections and rules for automatic rate selection when purchasing labels. Includes both default strategies (cheapest, fastest, best_value) and custom seller-configured rate shoppers.\n", "x-displayName": "Rate Shoppers" }, { "name": "service_points", "description": "Search for carrier service points (pickup and drop-off locations) where shipments can be delivered or picked up by customers.\n", "x-displayName": "Service Points" }, { "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": "tokens", "description": "Manage authentication tokens for accessing ShipStation services and dashboards.\n", "x-displayName": "Tokens" }, { "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": { "product": { "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", "null" ], "description": "Whether customs is required", "example": null }, "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 } } }, "carrier_name": { "title": "carrier_name", "type": "string", "enum": [ "access_worldwide", "amazon_buy_shipping", "amazon_shipping_uk", "apc", "asendia", "australia_post", "canada_post", "dhl_ecommerce", "dhl_express", "dhl_express_au", "dhl_express_ca", "dhl_express_uk", "dpd", "endicia", "epg_shipping", "fedex", "fedex_uk", "firstmile", "imex", "newgistics", "ontrac", "purolator_canada", "royal_mail", "seko", "sendle", "stamps_com", "ups" ], "description": "The carrier name" }, "carrier_name_with_settings": { "title": "carrier_name_with_settings", "type": "string", "enum": [ "dhl_express", "fedex", "newgistics", "ups" ], "description": "The shipping carriers for which ShipStation supports carrier settings" }, "add_funds_to_carrier_request_body": { "title": "add_funds_to_carrier_request_body", "description": "An add funds to carrier request body", "additionalProperties": false, "allOf": [ { "$ref": "#/components/schemas/monetary_value" } ] }, "add_funds_to_carrier_response_body": { "title": "add_funds_to_carrier_response_body", "type": "object", "description": "The current balance of the requested carrier account", "required": [ "balance" ], "additionalProperties": false, "properties": { "balance": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/monetary_value" } ], "description": "The current balance of the account" } } }, "connect_carrier_request_body": { "title": "connect_carrier_request_body", "anyOf": [ { "$ref": "#/components/schemas/connect_access_worldwide_request_body" }, { "$ref": "#/components/schemas/connect_amazon_buy_shipping_request_body" }, { "$ref": "#/components/schemas/connect_amazon_shipping_uk" }, { "$ref": "#/components/schemas/connect_apc_request_body" }, { "$ref": "#/components/schemas/connect_asendia_request_body" }, { "$ref": "#/components/schemas/connect_australia_post_request_body" }, { "$ref": "#/components/schemas/connect_canada_post_request_body" }, { "$ref": "#/components/schemas/connect_dhl_ecommerce_request_body" }, { "$ref": "#/components/schemas/connect_dhl_express_request_body" }, { "$ref": "#/components/schemas/connect_dhl_express_au_request_body" }, { "$ref": "#/components/schemas/connect_dhl_express_ca_request_body" }, { "$ref": "#/components/schemas/connect_dhl_express_uk_request_body" }, { "$ref": "#/components/schemas/connect_dpd_request_body" }, { "$ref": "#/components/schemas/connect_endicia_request_body" }, { "$ref": "#/components/schemas/connect_epg_shipping_request_body" }, { "$ref": "#/components/schemas/connect_fedex_request_body" }, { "$ref": "#/components/schemas/connect_fedex_uk_request_body" }, { "$ref": "#/components/schemas/connect_firstmile_request_body" }, { "$ref": "#/components/schemas/connect_imex_request_body" }, { "$ref": "#/components/schemas/connect_lasership_request_body" }, { "$ref": "#/components/schemas/connect_newgistics_request_body" }, { "$ref": "#/components/schemas/connect_ontrac_request_body" }, { "$ref": "#/components/schemas/connect_purolator_request_body" }, { "$ref": "#/components/schemas/connect_royal_mail_request_body" }, { "$ref": "#/components/schemas/connect_seko_request_body" }, { "$ref": "#/components/schemas/connect_sendle_request_body" }, { "$ref": "#/components/schemas/connect_stamps_request_body" }, { "$ref": "#/components/schemas/connect_ups_request_body" } ] }, "connect_carrier_response_body": { "title": "connect_carrier_response_body", "type": "object", "description": "A connect account response body", "required": [ "carrier_id" ], "additionalProperties": false, "properties": { "carrier_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "A string that uniquely identifies the carrier" } } }, "get_carrier_settings_response_body": { "title": "get_carrier_settings_response_body", "oneOf": [ { "$ref": "#/components/schemas/dhl_express_settings_response_body" }, { "$ref": "#/components/schemas/fedex_settings_response_body" }, { "$ref": "#/components/schemas/ups_settings_response_body" } ] }, "update_carrier_settings_request_body": { "title": "update_carrier_settings_request_body", "anyOf": [ { "$ref": "#/components/schemas/update_dhl_express_settings_request_body" }, { "$ref": "#/components/schemas/update_fedex_settings_request_body" }, { "$ref": "#/components/schemas/update_newgistics_settings_request_body" }, { "$ref": "#/components/schemas/update_ups_settings_request_body" }, { "$ref": "#/components/schemas/update_amazon_buy_shipping_request_body" } ] }, "empty_response_body": { "title": "empty_response_body", "type": "string", "minLength": 0, "maxLength": 0 }, "connect_access_worldwide_request_body": { "title": "connect_access_worldwide_request_body", "type": "object", "description": "An Access Worldwide account information request body", "required": [ "nickname", "username", "password" ], "additionalProperties": false, "properties": { "nickname": { "type": "string", "minLength": 1, "example": "Stamps.com", "description": "The nickname associated with the carrier connection" }, "username": { "type": "string", "example": "your_username", "minLength": 1, "description": "Access Worldwide Username" }, "password": { "type": "string", "example": "your_password", "minLength": 1, "description": "Access Worldwide Password" } } }, "connect_amazon_buy_shipping_request_body": { "title": "connect_amazon_buy_shipping_request_body", "type": "object", "description": "An Amazon account information request body", "required": [ "nickname", "merchant_seller_id", "email", "mws_auth_token" ], "additionalProperties": false, "properties": { "nickname": { "type": "string", "minLength": 1, "example": "Test Amazon Buy Shipping", "description": "Nickname to be associated with the account connection" }, "merchant_seller_id": { "type": "string", "example": "A1B2C3D4E5F6G7", "minLength": 1 }, "mws_auth_token": { "type": "string", "example": "amzn.mws.12345678-1234-1234-1234-123456789012", "minLength": 1 }, "email": { "$ref": "#/components/schemas/email" } } }, "email": { "title": "email", "type": "string", "format": "email", "minLength": 1, "example": "john.doe@example.com", "description": "An email address." }, "connect_amazon_shipping_uk": { "title": "connect_amazon_shipping_uk", "type": "object", "description": "An Amazon Shipping UK account information request body", "required": [ "nickname", "auth_code" ], "additionalProperties": false, "properties": { "nickname": { "type": "string", "minLength": 1, "example": "Stamps.com", "description": "The nickname associated with the carrier connection" }, "auth_code": { "type": "string", "example": "your_auth_code", "minLength": 1, "description": "Amazon UK Shipping auth code." } } }, "connect_apc_request_body": { "title": "connect_apc_request_body", "type": "object", "description": "An APC account information request body", "required": [ "nickname", "username", "password" ], "additionalProperties": false, "properties": { "nickname": { "type": "string", "minLength": 1, "example": "APC carrier account", "description": "The nickname for the APC account" }, "username": { "type": "string", "minLength": 1, "example": "john_doe", "description": "The username for the APC account" }, "password": { "type": "string", "minLength": 1, "example": "12345", "description": "The password for the APC account" } } }, "connect_asendia_request_body": { "title": "connect_asendia_request_body", "type": "object", "description": "An Asendia account information request body", "required": [ "nickname", "account_number", "username", "password", "api_key", "processing_location" ], "additionalProperties": false, "properties": { "nickname": { "type": "string", "minLength": 1, "example": "Asendia account", "description": "The nickname of the Asendia account" }, "account_number": { "type": "string", "example": "123456", "minLength": 1, "description": "Asendia account number" }, "username": { "type": "string", "example": "your_username", "minLength": 1, "description": "Asendia username" }, "password": { "type": "string", "example": "your_password", "minLength": 1, "description": "Asendia password" }, "api_key": { "type": "string", "example": "your_api_key", "minLength": 1, "description": "Asendia api_key" }, "processing_location": { "type": "string", "example": "MIA", "minLength": 1, "description": "Asendia processing location, one of: 'MIA', 'JFK', 'ORD', 'PHL', 'SFO', 'LAX', 'SLC', 'TOR', 'BUF', 'CAL'" }, "sub_account_number": { "type": "string", "example": "SUB123456", "minLength": 1, "description": "Asendia sub account number" } } }, "connect_australia_post_request_body": { "title": "connect_australia_post_request_body", "type": "object", "description": "An Australia Post account information request body", "required": [ "account_number", "api_key", "api_secret", "nickname" ], "additionalProperties": false, "properties": { "account_number": { "type": "string", "example": "123456", "minLength": 1, "description": "Account number" }, "api_key": { "type": "string", "example": "your_api_key", "minLength": 1, "description": "API key" }, "api_secret": { "type": "string", "example": "your_api_secret", "minLength": 1, "description": "API secret" }, "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" } } }, "connect_canada_post_request_body": { "title": "connect_canada_post_request_body", "type": "object", "description": "A Canada Post account information request body", "required": [ "nickname", "api_key", "api_secret", "account_number", "contract_id" ], "additionalProperties": false, "properties": { "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" }, "api_key": { "type": "string", "example": "your_api_key", "minLength": 1, "description": "Canada Post Account API Key" }, "api_secret": { "type": "string", "example": "your_api_secret", "minLength": 1, "description": "Canada Post Account API Secret" }, "account_number": { "type": "string", "example": "123456", "minLength": 1, "description": "Canada Post Account Number" }, "contract_id": { "type": "string", "example": "123456789", "minLength": 1, "description": "Canada Post Account Contract ID" } } }, "connect_dhl_ecommerce_request_body": { "title": "connect_dhl_ecommerce_request_body", "type": "object", "description": "A DHL Ecommerce account information request body", "required": [ "nickname", "client_id", "username", "password", "pickup_number", "distribution_center" ], "additionalProperties": false, "properties": { "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "A nickname to help you identify this account" }, "client_id": { "type": "string", "example": "your_client_id", "minLength": 1, "description": "The client id" }, "username": { "type": "string", "example": "your_username", "minLength": 1, "description": "The account username" }, "password": { "type": "string", "example": "your_password", "minLength": 1, "description": "The account password" }, "pickup_number": { "type": "string", "example": "PU123456", "minLength": 1, "description": "The pickup number" }, "distribution_center": { "type": "string", "example": "LAX", "minLength": 1, "description": "The distribution center" }, "api_key": { "type": "string", "example": "your_api_key", "minLength": 1, "description": "The DHL E-Commerce API key. This field is optional, but if not set you will not be able to get rates for this account.\n" }, "api_secret": { "type": "string", "example": "your_api_secret", "minLength": 1, "description": "The DHL E-Commerce API secret. This field is optional, but if not set you will not be able to get rates for this account.\n" }, "ancillary_endorsement": { "$ref": "#/components/schemas/ancillary_service_endorsement" }, "account_number": { "type": "string", "example": "123456", "minLength": 1, "deprecated": true, "description": "Account number" }, "ftp_username": { "type": "string", "example": "your_ftp_username", "minLength": 1, "deprecated": true, "description": "FTP username" }, "ftp_password": { "type": "string", "example": "your_ftp_password", "minLength": 1, "deprecated": true, "description": "FTP password" }, "sold_to": { "type": "string", "example": "123456", "description": "Sold To field" }, "registration_id": { "type": "string", "example": "REG123456" }, "software_name": { "type": "string", "example": "ShipStation" } } }, "ancillary_service_endorsement": { "title": "ancillary_service_endorsement", "type": "string", "enum": [ "none", "return_service_requested", "forwarding_service_requested", "address_service_requested", "change_service_requested", "leave_if_no_response" ], "description": "[Ancillary service endorsements](https://pe.usps.com/text/qsg300/Q507.htm) are used by mailers to request an addressee's new address and to provide the carrier with instructions on how to handle packages that are undeliverable as addressed.\n\n| Ancillary Service Endorsement | Description\n|--------------------------------|-----------------------------------------------------\n| `none` | No ancillary service is requested. Depending on the carrier servive, the package may be forwarded, returned, or discarded.\n| `return_service_requested` | The package is returned to the sender. If possible, notification of the new address is is included with the returned package.\n| `forwarding_service_requested` | Forward the package to the new address, if possible; otherwise, return it to the sender.\n| `address_service_requested` | Forward the package to the new address, if possible; otherwise, return it to the sender. This is similar to `forwarding_service_requested`, but different restrictions and charges may apply.\n| `change_service_requested` | The package is discarded. If possible, notification of the new address is sent to the sender.\n| `leave_if_no_response` |\n" }, "connect_dhl_express_request_body": { "title": "connect_dhl_express_request_body", "type": "object", "description": "A DHL express account information request body", "required": [ "nickname", "account_number" ], "additionalProperties": false, "properties": { "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" }, "account_number": { "type": "string", "example": "123456", "minLength": 1, "description": "Account number" }, "site_id": { "type": "string", "example": "SITE123", "minLength": 1, "description": "Required if password is provided" }, "password": { "type": "string", "example": "your_password", "minLength": 1, "description": "Required if site id is provided" }, "country_code": { "$ref": "#/components/schemas/country_code" } } }, "connect_dhl_express_au_request_body": { "title": "connect_dhl_express_au_request_body", "type": "object", "description": "A DHL Express AU account information request body", "required": [ "nickname", "account_number" ], "additionalProperties": false, "properties": { "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" }, "account_number": { "type": "string", "example": "123456", "minLength": 1, "description": "Account number" } } }, "connect_dhl_express_ca_request_body": { "title": "connect_dhl_express_ca_request_body", "type": "object", "description": "A DHL Express CA account information request body", "required": [ "nickname", "account_number" ], "additionalProperties": false, "properties": { "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" }, "account_number": { "type": "string", "example": "123456", "minLength": 1, "description": "Account number" } } }, "connect_dhl_express_uk_request_body": { "title": "connect_dhl_express_uk_request_body", "type": "object", "description": "A DHL Express UK account information request body", "required": [ "account_number", "site_id", "password", "nickname" ], "additionalProperties": false, "properties": { "account_number": { "type": "string", "example": "123456", "minLength": 1, "description": "Account number" }, "site_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "A string that uniquely identifies the site" }, "password": { "type": "string", "example": "your_password", "minLength": 1, "description": "Password" }, "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" } } }, "connect_dpd_request_body": { "title": "connect_dpd_request_body", "type": "object", "description": "A DPD account information request body", "required": [ "account_number", "password", "nickname" ], "additionalProperties": false, "properties": { "account_number": { "type": "string", "example": "123456", "minLength": 1, "description": "Account number" }, "password": { "type": "string", "example": "your_password", "minLength": 1, "description": "Password" }, "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" } } }, "connect_endicia_request_body": { "title": "connect_endicia_request_body", "type": "object", "description": "An Endicia account information request body", "required": [ "nickname", "account", "passphrase" ], "additionalProperties": false, "properties": { "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" }, "account": { "type": "string", "example": "123456", "minLength": 1, "description": "Account" }, "passphrase": { "type": "string", "example": "your_passphrase", "minLength": 1, "description": "Passphrase" } } }, "connect_epg_shipping_request_body": { "title": "connect_epg_shipping_request_body", "type": "object", "description": "An EPG (ePost Global) account information request body", "required": [ "nickname", "token" ], "additionalProperties": false, "properties": { "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" }, "token": { "type": "string", "example": "your_token", "minLength": 1, "description": "Token" } } }, "connect_fedex_request_body": { "title": "connect_fedex_request_body", "type": "object", "description": "A Fedex account information request body", "required": [ "account_number", "address1", "city", "country_code", "email", "first_name", "last_name", "phone", "postal_code", "state", "nickname", "agree_to_eula" ], "additionalProperties": false, "properties": { "account_number": { "type": "string", "example": "123456", "minLength": 1, "description": "Account number" }, "address1": { "type": "string", "example": "123 Main St", "minLength": 1, "description": "Address" }, "address2": { "type": "string", "example": "Suite 100", "minLength": 1, "description": "Address" }, "city": { "type": "string", "example": "Austin", "minLength": 1, "description": "The city" }, "company": { "type": "string", "example": "ACME Corporation", "minLength": 1, "description": "The company" }, "country_code": { "type": "string", "example": "US", "minLength": 1, "description": "Country code" }, "email": { "allOf": [ { "$ref": "#/components/schemas/email" } ], "description": "The email address" }, "first_name": { "type": "string", "example": "John", "minLength": 1, "description": "First name" }, "last_name": { "type": "string", "example": "Doe", "minLength": 1, "description": "Last name" }, "phone": { "type": "string", "example": "+1 (555) 123-4567", "minLength": 1, "description": "Phone number" }, "postal_code": { "type": "string", "example": "78701", "minLength": 1, "description": "Postal Code" }, "state": { "type": "string", "example": "TX", "minLength": 1, "description": "State" }, "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" }, "agree_to_eula": { "type": "boolean", "example": true, "description": "Boolean signaling agreement to the Fedex End User License Agreement" }, "meter_number": { "type": "string", "example": "123456789", "minLength": 1, "description": "Meter number" } } }, "connect_fedex_uk_request_body": { "title": "connect_fedex_uk_request_body", "type": "object", "description": "A Fedex UK account information request body", "required": [ "account_number", "address1", "city", "country_code", "email", "first_name", "last_name", "phone", "postal_code", "state", "nickname", "agree_to_eula" ], "additionalProperties": false, "properties": { "account_number": { "type": "string", "example": "123456", "minLength": 1, "description": "Account number" }, "address1": { "type": "string", "example": "123 Main St", "minLength": 1, "description": "Address" }, "address2": { "type": "string", "example": "Suite 100", "minLength": 1, "description": "Address" }, "city": { "type": "string", "example": "Austin", "minLength": 1, "description": "The city" }, "company": { "type": "string", "example": "ACME Corporation", "minLength": 1, "description": "The company" }, "country_code": { "type": "string", "example": "US", "minLength": 1, "description": "Country code" }, "email": { "allOf": [ { "$ref": "#/components/schemas/email" } ], "description": "The email address" }, "first_name": { "type": "string", "example": "John", "minLength": 1, "description": "First name" }, "last_name": { "type": "string", "example": "Doe", "minLength": 1, "description": "Last name" }, "phone": { "type": "string", "example": "+1 (555) 123-4567", "minLength": 1, "description": "Phone number" }, "postal_code": { "type": "string", "example": "78701", "minLength": 1, "description": "Postal Code" }, "state": { "type": "string", "example": "TX", "minLength": 1, "description": "State" }, "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" }, "agree_to_eula": { "type": "boolean", "example": true, "description": "Boolean signaling agreement to the Fedex End User License Agreement" }, "meter_number": { "type": "string", "example": "123456789", "minLength": 1, "description": "Meter number" } } }, "connect_firstmile_request_body": { "title": "connect_firstmile_request_body", "type": "object", "description": "A First Mile account information request body", "required": [ "nickname", "mailer_id", "password" ], "additionalProperties": false, "properties": { "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" }, "mailer_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "A string that uniquely identifies the mailer" }, "profile_name": { "type": "string", "example": "Default Profile", "minLength": 1, "description": "Profile name" }, "password": { "type": "string", "example": "your_password", "minLength": 1, "description": "Password" } } }, "connect_imex_request_body": { "title": "connect_imex_request_body", "type": "object", "description": "An Imex account information request body", "required": [ "nickname", "username", "password" ], "additionalProperties": false, "properties": { "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" }, "username": { "type": "string", "example": "your_username", "minLength": 1, "description": "Username" }, "password": { "type": "string", "example": "your_password", "minLength": 1, "description": "Password" } } }, "connect_lasership_request_body": { "title": "connect_lasership_request_body", "type": "object", "description": "A Lasership account information request body", "required": [ "nickname", "web_services_id", "web_services_key", "customer_branch", "Address", "PostalCode", "City", "State", "lasership_critical_pull_time", "lasership_critical_entry_time" ], "additionalProperties": false, "properties": { "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" }, "web_services_id": { "type": "string", "example": "WS123456", "minLength": 1, "description": "Web Service ID (WSID)" }, "web_services_key": { "type": "string", "example": "your_web_services_key", "minLength": 1, "description": "Web Service Key (WSKey)" }, "customer_branch": { "type": "string", "example": "BRANCH01", "minLength": 1, "description": "Customer Branch" }, "Address": { "type": "string", "example": "123 Main St", "description": "Address" }, "Address2": { "type": "string", "example": "Suite 100", "description": "Address2" }, "PostalCode": { "type": "string", "example": "78701", "description": "PostalCode" }, "City": { "type": "string", "example": "Austin", "description": "City" }, "State": { "type": "string", "example": "TX", "description": "State" }, "country": { "type": "string", "example": "US", "description": "Country" }, "Phone": { "type": "string", "example": "+1 (555) 123-4567", "description": "Phone" }, "Email": { "type": "string", "example": "john.doe@example.com", "description": "Email" }, "instructions": { "type": "string", "example": "Handle with care", "description": "Instructions" }, "facility_code": { "type": "string", "example": "FAC001", "description": "Facility Code" }, "lasership_critical_pull_time": { "type": "string", "example": "16:00", "description": "Critical Pull Time (local time)" }, "lasership_critical_entry_time": { "type": "string", "example": "14:00", "description": "Critical Entry Time (local time)" }, "declare_piece_attributes_separately_for_every_shipment": { "type": "boolean", "example": false, "description": "Declare piece attributes separately for every shipment, overrides individual attribute below.", "default": false }, "AttrAlcohol": { "type": "boolean", "example": false, "description": "Set this to true if your shipments will always contain Alcohol" }, "AttrDryIce": { "type": "boolean", "example": false, "description": "Set this to true if your shipments will always contain DryIce" }, "AttrHazmat": { "type": "boolean", "example": false, "description": "Set this to true if your shipments will always contain Hazmat" }, "AttrTwoPersons": { "type": "boolean", "example": false, "description": "Set this to true if your shipments will always require Two Persons" }, "AttrExplosive": { "type": "boolean", "example": false, "description": "Set this to true if your shipments will always contain Explosives" }, "AttrControlledSubstance": { "type": "boolean", "example": false, "description": "Set this to true if your shipments will always contain Controlled Substances" }, "AttrRefrigerated": { "type": "boolean", "example": false, "description": "Set this to true if your shipments will always require Refrigeration" }, "AttrPerishable": { "type": "boolean", "example": false, "description": "Set this to true if your shipments will always be Perishable" }, "AttrNoRTS": { "type": "boolean", "example": false, "description": "Set this to true if your shipments will always use \"No Return To Sender\"" } } }, "connect_newgistics_request_body": { "title": "connect_newgistics_request_body", "type": "object", "description": "A Newgistics account information request body", "required": [ "induction_site", "nickname" ], "additionalProperties": false, "properties": { "merchant_id": { "type": "integer", "example": 123456, "format": "int32", "minimum": 0, "description": "Merchant id" }, "mailer_id": { "type": "integer", "example": 789012, "format": "int32", "minimum": 0, "description": "Mailer id" }, "induction_site": { "type": "string", "example": "SITE01", "minLength": 1, "description": "Induction site" }, "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" } } }, "connect_ontrac_request_body": { "title": "connect_ontrac_request_body", "type": "object", "description": "An Ontrac account information request body", "required": [ "nickname", "account_number", "password" ], "additionalProperties": false, "properties": { "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" }, "account_number": { "type": "string", "example": "123456", "minLength": 1, "description": "Account number" }, "password": { "type": "string", "example": "your_password", "minLength": 1, "description": "Password" } } }, "connect_purolator_request_body": { "title": "connect_purolator_request_body", "type": "object", "description": "A Purolator account information request body", "required": [ "account_number", "activation_key", "nickname" ], "additionalProperties": false, "properties": { "account_number": { "type": "string", "example": "123456", "minLength": 1, "description": "Account number" }, "activation_key": { "type": "string", "example": "ACT123456789", "minLength": 1, "description": "Activation key" }, "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" } } }, "connect_royal_mail_request_body": { "title": "connect_royal_mail_request_body", "type": "object", "description": "A Royal Mail account information request body", "required": [ "account_number", "contact_name", "city", "postal_code", "nickname" ], "additionalProperties": false, "properties": { "account_number": { "type": "string", "example": "123456", "minLength": 1, "description": "Account number" }, "oba_email": { "allOf": [ { "$ref": "#/components/schemas/email" } ], "description": "The oba email address" }, "contact_name": { "type": "string", "example": "John Doe", "minLength": 1, "description": "Contact name" }, "email": { "allOf": [ { "$ref": "#/components/schemas/email" } ], "description": "The email address" }, "company_name": { "type": "string", "example": "ACME Corporation", "minLength": 1, "description": "Company name" }, "street_line1": { "type": "string", "example": "123 Main St", "minLength": 1, "description": "Street line1" }, "street_line2": { "type": "string", "example": "Suite 100", "minLength": 1, "description": "Street line2" }, "street_line3": { "type": "string", "example": "Floor 3", "minLength": 1, "description": "Street line3" }, "city": { "type": "string", "example": "Austin", "minLength": 1, "description": "City" }, "postal_code": { "type": "string", "example": "78701", "minLength": 1, "description": "Postal code" }, "phone": { "type": "string", "example": "+1 (555) 123-4567", "minLength": 1, "description": "Phone" }, "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" } } }, "connect_seko_request_body": { "title": "connect_seko_request_body", "type": "object", "description": "A SEKO account information request body", "required": [ "nickname", "access_key" ], "additionalProperties": false, "properties": { "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" }, "access_key": { "type": "string", "example": "your_access_key", "minLength": 1, "description": "Seko Account Access Key" } } }, "connect_sendle_request_body": { "title": "connect_sendle_request_body", "type": "object", "description": "A Sendle account information request body", "required": [ "nickname", "sendle_id", "api_key" ], "additionalProperties": false, "properties": { "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" }, "sendle_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "A string that uniquely identifies the sendle" }, "api_key": { "type": "string", "example": "your_api_key", "minLength": 1, "description": "API key" } } }, "connect_stamps_request_body": { "title": "connect_stamps_request_body", "type": "object", "description": "A Stamps account information request body", "required": [ "nickname", "username", "password" ], "additionalProperties": false, "properties": { "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" }, "username": { "type": "string", "example": "your_username", "minLength": 1, "description": "Username" }, "password": { "type": "string", "example": "your_password", "minLength": 1, "description": "Password" } } }, "connect_ups_request_body": { "title": "connect_ups_request_body", "type": "object", "description": "A UPS account information request body. The location header from this call should be used to redirect to UPS for sign in.", "required": [ "nickname", "account_number", "account_postal_code", "account_country_code" ], "additionalProperties": false, "properties": { "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Nickname" }, "account_number": { "type": "string", "example": "123456", "minLength": 1, "description": "Account number" }, "account_postal_code": { "type": "string", "example": "78701", "minLength": 1, "description": "Account Postal Code" }, "account_country_code": { "type": "string", "example": "US", "minLength": 1, "description": "Account Country Code" } } }, "dhl_express_settings_response_body": { "title": "dhl_express_settings_response_body", "description": "A DHL Express response body", "additionalProperties": false, "allOf": [ { "$ref": "#/components/schemas/dhl_express_account_settings" } ] }, "dhl_express_account_settings": { "title": "dhl_express_account_settings", "type": "object", "description": "A DHL Express account settings", "additionalProperties": false, "properties": { "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Account nickname" }, "should_hide_account_number_on_archive_doc": { "type": "boolean", "example": false, "description": "Indicates if the account number should be hidden on the archive documentation" }, "is_primary_account": { "type": "boolean", "example": false, "description": "Indicates if this is primary account" } } }, "fedex_settings_response_body": { "title": "fedex_settings_response_body", "description": "A Fedex settings response body", "additionalProperties": false, "allOf": [ { "$ref": "#/components/schemas/fedex_account_settings_request_body" } ] }, "fedex_account_settings_request_body": { "title": "fedex_account_settings_request_body", "description": "A Fedex account settings request body", "additionalProperties": false, "allOf": [ { "$ref": "#/components/schemas/fedex_account_settings" } ] }, "fedex_account_settings": { "title": "fedex_account_settings", "type": "object", "description": "A Fedex account settings request body", "additionalProperties": false, "properties": { "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "Account nickname" }, "pickup_type": { "$ref": "#/components/schemas/fedex_pickup_type" }, "smart_post_hub": { "$ref": "#/components/schemas/smart_post_hub" }, "smart_post_endorsement": { "$ref": "#/components/schemas/ancillary_service_endorsement" }, "is_primary_account": { "type": "boolean", "example": false }, "signature_image": { "type": "string", "example": "base64_encoded_signature" }, "letterhead_image": { "type": "string", "example": "base64_encoded_image" } } }, "fedex_pickup_type": { "title": "fedex_pickup_type", "type": "string", "enum": [ "none", "regular_pickup", "request_courier", "drop_box", "business_service_center", "station" ], "description": "Tax identifier type for customs declaration\n\n|Pickup Type |Description\n|--------------------------|-----------------------------------------\n|`none` | Not specified\n|`regular_pickup` | You already have a daily pickup scheduled with FedEx\n|`request_courier` | You will call FedEx to request a courier\n|`drop_box` | You will drop-off packages in a FedEx drop box\n|`business_service_center` | You will drop-off packages at an authorized FedEx business service center\n|`station` | You will drop-off the package at a FedEx Station\n" }, "smart_post_hub": { "title": "smart_post_hub", "type": "string", "enum": [ "none", "allentown_pa", "atlanta_ga", "baltimore_md", "charlotte_nc", "chino_ca", "dallas_tx", "denver_co", "detroit_mi", "edison_nj", "grove_city_oh", "groveport_oh", "houston_tx", "indianapolis_in", "kansas_city_ks", "los_angeles_ca", "martinsburg_wv", "memphis_tn", "minneapolis_mn", "new_berlin_wi", "northborough_ma", "orlando_fl", "phoneix_az", "pittsburgh_pa", "reno_nv", "sacramento_ca", "salt_lake_city_ut", "seattle_wa", "st_louis_mo", "windsor_ct", "newark_ny", "south_brunswick_nj", "scranton_pa", "wheeling_il", "middletown_ct", "portland_or" ], "description": "The possible smart post hub values" }, "ups_settings_response_body": { "title": "ups_settings_response_body", "description": "A UPS settings response body", "additionalProperties": false, "allOf": [ { "$ref": "#/components/schemas/ups_account_settings" } ] }, "ups_account_settings": { "title": "ups_account_settings", "type": "object", "description": "UPS account settings", "additionalProperties": false, "properties": { "nickname": { "type": "string", "example": "My Carrier Account", "minLength": 1, "description": "nickname" }, "is_primary_account": { "type": "boolean", "example": false, "description": "Indicates if this is the primary UPS account" }, "pickup_type": { "$ref": "#/components/schemas/ups_pickup_type" }, "use_carbon_neutral_shipping_program": { "type": "boolean", "example": false, "description": "The use carbon neutral shipping program" }, "use_ground_freight_pricing": { "type": "boolean", "example": false, "description": "The use ground freight pricing" }, "use_consolidation_services": { "type": "boolean", "example": false, "description": "The use consolidation services" }, "use_order_number_on_mail_innovations_labels": { "type": "boolean", "example": false, "description": "The use order number on mail innovations labels" }, "mail_innovations_endorsement": { "$ref": "#/components/schemas/ancillary_service_endorsement" }, "mail_innovations_cost_center": { "type": "string", "example": "CC123", "minLength": 0, "description": "mail innovations cost center" }, "use_negotiated_rates": { "type": "boolean", "example": false, "description": "The use negotiated rates" }, "account_postal_code": { "type": "string", "example": "78701", "minLength": 5, "description": "account postal code" }, "invoice": { "allOf": [ { "$ref": "#/components/schemas/ups_invoice" } ], "description": "The invoice" } } }, "ups_pickup_type": { "title": "ups_pickup_type", "type": "string", "enum": [ "daily_pickup", "occasional_pickup", "customer_counter" ], "description": "The possible ups pickup type values" }, "ups_invoice": { "title": "ups_invoice", "type": "object", "description": "UPS invoice", "additionalProperties": false, "properties": { "invoice_date": { "type": "string", "example": "2024-01-01T00:00:00.000Z", "format": "date-time", "minLength": 1, "description": "invoice date" }, "invoice_number": { "type": "string", "example": "INV-12345", "minLength": 1, "description": "invoice number" }, "control_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "A string that uniquely identifies the control" }, "invoice_amount": { "type": "number", "example": 100, "minimum": 0 }, "invoice_currency_code": { "type": "string", "example": "USD" } } }, "update_dhl_express_settings_request_body": { "title": "update_dhl_express_settings_request_body", "description": "An update dhl express settings request body", "additionalProperties": false, "allOf": [ { "$ref": "#/components/schemas/dhl_express_account_settings" } ] }, "update_fedex_settings_request_body": { "title": "update_fedex_settings_request_body", "description": "An update Fedex settings request body", "additionalProperties": false, "allOf": [ { "$ref": "#/components/schemas/fedex_account_settings" } ] }, "update_newgistics_settings_request_body": { "title": "update_newgistics_settings_request_body", "type": "object", "description": "A newgistics account settings request body", "additionalProperties": false, "properties": { "include_barcode_with_order_number": { "type": "boolean", "example": false }, "receive_email_on_manifest_processing": { "type": "boolean", "example": false } } }, "update_ups_settings_request_body": { "title": "update_ups_settings_request_body", "description": "An update UPS settings request body", "additionalProperties": false, "allOf": [ { "$ref": "#/components/schemas/ups_account_settings" } ] }, "update_amazon_buy_shipping_request_body": { "title": "update_amazon_buy_shipping_request_body", "type": "object", "description": "An amazon buy shipping account settings request body", "additionalProperties": false, "properties": { "email": { "type": "string", "example": "john.doe@example.com", "minLength": 1, "description": "Email" } } }, "update_warehouse_request_body": { "title": "update_warehouse_request_body", "description": "An update warehouse request body", "required": [ "name", "origin_address" ], "additionalProperties": false, "allOf": [ { "$ref": "#/components/schemas/warehouse" } ] }, "update_warehouse_settings_request_body": { "title": "update_warehouse_settings_request_body", "type": "object", "description": "An update warehouse settings request body", "properties": { "is_default": { "type": "boolean", "example": false, "description": "The default property on the warehouse." } } }, "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": { "allOf": [ { "$ref": "#/components/schemas/monetary_value" } ], "description": "Fee charged for the fulfillment" }, "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", "null" ], "format": "int32", "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", "null" ], "readOnly": true, "minLength": 1, "example": "package", "description": "package type that this rate was estimated for" }, "delivery_days": { "type": [ "integer", "null" ], "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, "oneOf": [ { "$ref": "#/components/schemas/date" }, { "type": "null" } ] }, "carrier_delivery_days": { "type": [ "string", "null" ], "readOnly": true, "minLength": 1, "example": "22", "description": "The carrier delivery days" }, "delivery_prediction": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/delivery_prediction" } ], "description": "ShipStation's predicted estimated delivery date." }, "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", "null" ], "maxLength": 50, "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", "null" ], "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) shipped. 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" }, "delivery_prediction": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/delivery_prediction" } ], "description": "ShipStation's predicted delivery estimate for this label. This is the only delivery estimate in a label response; it is omitted when no prediction is available." }, "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", "null" ], "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": { "readOnly": true, "oneOf": [ { "$ref": "#/components/schemas/date_time" }, { "type": "null" } ], "description": "The date and time that the label was [voided] , or `null` if the label has not been voided\n" }, "void_type": { "readOnly": true, "oneOf": [ { "$ref": "#/components/schemas/void_type" }, { "type": "null" } ], "description": "Indicates how the label was voided. This field is `null` if the label has not been voided.\n", "example": "manual" }, "refund_details": { "readOnly": true, "oneOf": [ { "$ref": "#/components/schemas/refund_details" }, { "type": "null" } ], "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": { "oneOf": [ { "$ref": "#/components/schemas/image_id" }, { "type": "null" } ], "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 for this shipment. Defaults to 'none' if not specified.." }, "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, "oneOf": [ { "$ref": "#/components/schemas/link" }, { "type": "null" } ], "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, "oneOf": [ { "$ref": "#/components/schemas/optional_link" }, { "type": "null" } ], "description": "The QR code download for the package" }, "paperless_download": { "readOnly": true, "oneOf": [ { "$ref": "#/components/schemas/paperless_download" }, { "type": "null" } ], "description": "The paperless details which may contain elements like `href`, `instructions` and `handoff_code`.\n" }, "insurance_claim": { "readOnly": true, "oneOf": [ { "$ref": "#/components/schemas/link" }, { "type": "null" } ], "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", "null" ], "readOnly": true, "description": "Alternative identifiers associated with this package.\n", "items": { "$ref": "#/components/schemas/alternative_identifier" } } } } ] } }, "alternative_identifiers": { "type": [ "array", "null" ], "readOnly": 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, "description": "A breakdown of individual charges that make up this label, such as base shipping cost and additional fees. For DDP shipments it also includes duties, taxes, and import fees (prepaid on Wallet carriers, estimated on BYOA carriers).\n", "items": { "$ref": "#/components/schemas/rate_detail" } }, "tracking_url": { "readOnly": true, "type": [ "string", "null" ], "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", "null" ], "readOnly": true, "minLength": 0, "example": "12323aaaar", "description": "A string that uniquely identifies the external batch" }, "batch_notes": { "type": [ "string", "null" ], "readOnly": true, "default": "", "example": "Batch for morning shipment", "description": "Custom notes you can add for each created batch" }, "assigned_user": { "type": [ "string", "null" ], "format": "uuid", "readOnly": true, "example": "a2df9fa5-b7ee-467f-be4e-9c660542c187", "description": "The ID of the user assigned to the batch, or `null` if no user is assigned." }, "created_at": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/date_time" } ], "description": "The date and time the batch was created in ShipStation" }, "processed_at": { "readOnly": true, "oneOf": [ { "$ref": "#/components/schemas/date_time" }, { "type": "null" } ], "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": { "$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" }, "packing_slip_download": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/optional_link" } ], "description": "Link to download the packing slips for all shipments in the batch. Populated only when the batch was\ncreated or processed with `generate_packing_slips` set to `true`; otherwise an empty object.\nThe file is available once the batch has been processed.\n" }, "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/station/events", "description": "The webhook payload listener URL that you intend to target for webhook dispatches" }, "event": { "$ref": "#/components/schemas/webhook_event" }, "headers": { "type": "array", "items": { "$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": { "type": [ "boolean", "null" ], "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": { "$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", "null" ], "maxLength": 500, "example": "Packaging for laptops", "description": "Provides a helpful description for the custom package." } } }, "carrier_provided_package_type": { "title": "carrier_provided_package_type", "type": "object", "description": "A package type that a carrier provides for shipment. Unlike custom packages, carrier packages do not have a package_id.", "required": [ "name", "package_code" ], "additionalProperties": false, "properties": { "package_id": { "anyOf": [ { "$ref": "#/components/schemas/se_id" }, { "type": "null" } ], "description": "This field is `null` for package types that the carrier shares across accounts. Package IDs are assigned to packages that belong to your account, such as custom packages." }, "package_code": { "$ref": "#/components/schemas/package_code" }, "name": { "type": "string", "minLength": 1, "maxLength": 50, "example": "Small Flat Rate Box" }, "dimensions": { "allOf": [ { "$ref": "#/components/schemas/dimensions" } ], "description": "The dimensions for the package." }, "description": { "type": [ "string", "null" ], "maxLength": 500, "example": "USPS Small Flat Rate Box", "description": "Provides a helpful description for the 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", "insurance_provider", "tags", "packages", "total_weight", "batch_ids" ], "additionalProperties": false, "allOf": [ { "$ref": "#/components/schemas/partial_shipment" }, { "title": "shipment_sales_order_fields", "type": "object", "properties": { "sales_order_ids": { "type": "array", "readOnly": true, "items": { "type": "string" }, "description": "The IDs of the sales orders that the shipment is linked to. The array is empty if the shipment\nisn't linked to a sales order. This field is read-only and is ignored in requests.\n\nA shipment must be linked to a sales order before it can be\n[split](#operation/split_shipment) or [merged](#operation/merge_shipments).\n\n> **Note:** After a split, the original shipment can still list a sales order even if all of\nthat sales order's items have moved to other shipments. To see which sales order each item\nbelongs to, use `items[].sales_order_id`.\n", "example": [ "8c1f2a5e-3b7d-4e9a-a6c2-1d4f5e6a7b8c" ] } } } ] }, "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", "properties": { "shipment_id": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "A string that uniquely identifies the shipment" }, "carrier_id": { "oneOf": [ { "$ref": "#/components/schemas/se_id" }, { "type": "null" } ], "description": "The carrier account that is billed for the shipping charges", "example": "se-1234567" }, "service_code": { "oneOf": [ { "$ref": "#/components/schemas/service_code" }, { "type": "null" } ], "description": "The [carrier service] used to ship the package, such as `fedex_ground`, `usps_first_class_mail`, `flat_rate_envelope`, etc.\n", "example": "usps_first_class_mail" }, "requested_shipment_service": { "type": [ "string", "null" ], "description": "The requested shipment service", "example": "usps_priority_mail" }, "external_order_id": { "type": [ "string", "null" ], "example": "1232434", "description": "ID that the Order Source assigned" }, "hold_until_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date to hold the shipment until", "example": "2025-01-15T00:00:00.000Z" }, "ship_by_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date by which the shipment should be shipped", "example": "2025-01-15T00:00:00.000Z" }, "deliver_by_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date by which the shipment should be delivered", "example": "2025-01-20T00:00:00.000Z" }, "retail_rate": { "oneOf": [ { "$ref": "#/components/schemas/monetary_value" }, { "type": "null" } ], "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": { "$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", "null" ], "description": "Notes from the buyer", "example": "Please handle with care" }, "notes_to_buyer": { "type": [ "string", "null" ], "description": "Notes to the buyer", "example": "Thank you for your order!" }, "notes_for_gift": { "type": [ "string", "null" ], "description": "Gift notes", "example": "Happy Birthday!" }, "internal_notes": { "type": [ "string", "null" ], "description": "Internal notes from the seller", "example": "Check packaging before shipping" }, "is_gift": { "type": "boolean", "default": false, "description": "Indicates if the shipment is a gift", "example": true }, "assigned_user": { "type": [ "string", "null" ], "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", "null" ], "format": "int32", "minimum": 0, "description": "Shipping zone", "example": 1 }, "display_scheme": { "type": [ "string", "null" ], "description": "Display scheme for the shipment", "example": "label" }, "tax_identifiers": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/tax_identifier" } }, "external_shipment_id": { "type": [ "string", "null" ], "maxLength": 50, "example": "1234556", "description": "A user-defined key that identifies the source order. Multiple shipments can share the same `external_shipment_id` (common in split-shipping scenarios where one order results in multiple shipments). Functionally identical to `orderKey` in V1 API.\n\n> **Warning:** The `external_shipment_id` is limited to 50 characters. Any additional characters will be truncated.\n" }, "shipment_number": { "type": [ "string", "null" ], "maxLength": 50, "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": { "oneOf": [ { "$ref": "#/components/schemas/date" }, { "type": "null" } ], "description": "The date that the shipment was (or will be) shipped. 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": { "default": null, "oneOf": [ { "$ref": "#/components/schemas/se_id" }, { "type": "null" } ], "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", "null" ], "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 for this shipment. Defaults to 'none' if not specified." }, "customs": { "oneOf": [ { "$ref": "#/components/schemas/international_shipment_options" }, { "type": "null" } ], "description": "Customs information for international shipments.\n\n> **Note:** International shipments (where `ship_from.country_code` differs from `ship_to.country_code`) must include either `customs` or `advanced_options`.\n> To prepay duties and taxes (DDP / PDT), set `customs.terms_of_trade_code` to `ddp`.\n\n> Please note that the guaranteed prepaid duties and taxes option is available only for eligible ShipStation carriers.\n" }, "advanced_options": { "readOnly": false, "allOf": [ { "$ref": "#/components/schemas/advanced_shipment_options" } ], "description": "Advanced shipment options.\n\n> **Note:** International shipments must include either `customs` or `advanced_options`.\n" }, "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": { "$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": { "$ref": "#/components/schemas/order_source_name" }, "packages": { "type": "array", "minItems": 1, "items": { "$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" }, "batch_ids": { "readOnly": true, "type": "array", "default": [], "items": { "$ref": "#/components/schemas/se_id" }, "example": [ "se-9581628", "se-1935182" ], "description": "The unique IDs of any batches that this shipment is associated with. Returns an empty array if the shipment isn't associated with any batch.\n\nIf the shipment is associated with more than one batch, the IDs are ordered by batch status priority: `open`, `queued`, `processing`, `completed`, `completed_with_errors`, `archived`, `notifying`, then `invalid`.\n" }, "comparison_rate_type": { "type": [ "string", "null" ], "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", "null" ], "description": "The requested shipment service", "example": "usps_priority_mail" }, "external_order_id": { "type": [ "string", "null" ], "example": "1232434", "description": "ID that the Order Source assigned" }, "hold_until_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date to hold the shipment until", "example": "2025-01-15T00:00:00.000Z" }, "ship_by_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date by which the shipment should be shipped", "example": "2025-01-15T00:00:00.000Z" }, "deliver_by_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date by which the shipment should be delivered", "example": "2025-01-20T00:00:00.000Z" }, "retail_rate": { "oneOf": [ { "$ref": "#/components/schemas/monetary_value" }, { "type": "null" } ], "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": { "$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", "null" ], "description": "Notes from the buyer", "example": "Please handle with care" }, "notes_to_buyer": { "type": [ "string", "null" ], "description": "Notes to the buyer", "example": "Thank you for your order!" }, "notes_for_gift": { "type": [ "string", "null" ], "description": "Gift notes", "example": "Happy Birthday!" }, "internal_notes": { "type": [ "string", "null" ], "description": "Internal notes from the seller", "example": "Check packaging before shipping" }, "is_gift": { "type": "boolean", "default": false, "description": "Indicates if the shipment is a gift", "example": true }, "assigned_user": { "type": [ "string", "null" ], "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", "null" ], "format": "int32", "minimum": 0, "description": "Shipping zone", "example": 1 }, "display_scheme": { "type": [ "string", "null" ], "description": "Display scheme for the shipment", "example": "label" }, "tax_identifiers": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/tax_identifier" } }, "external_shipment_id": { "type": [ "string", "null" ], "maxLength": 50, "example": "1234556", "description": "A user-defined key that identifies the source order. Multiple shipments can share the same `external_shipment_id` (common in split-shipping scenarios where one order results in multiple shipments). Functionally identical to `orderKey` in V1 API.\n\n> **Warning:** The `external_shipment_id` is limited to 50 characters. Any additional characters will be truncated.\n" }, "shipment_number": { "type": [ "string", "null" ], "maxLength": 50, "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": { "oneOf": [ { "$ref": "#/components/schemas/date" }, { "type": "null" } ], "description": "The date that the shipment was (or will be) shipped. 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": { "default": null, "oneOf": [ { "$ref": "#/components/schemas/se_id" }, { "type": "null" } ], "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", "null" ], "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 for this shipment. Defaults to 'none' if not specified." }, "customs": { "oneOf": [ { "$ref": "#/components/schemas/international_shipment_options" }, { "type": "null" } ], "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": { "$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": { "$ref": "#/components/schemas/order_source_name" }, "packages": { "type": "array", "minItems": 1, "items": { "$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": { "type": [ "string", "null" ], "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" } } }, "compare_bulk_rates_request_body": { "title": "compare_bulk_rates_request_body", "type": "object", "description": "A rate shipments request body. Provide `shipment_ids`, `shipments`, or both. The API rejects a request that includes neither, and rates at most 100 shipments per request, counting both arrays together.", "additionalProperties": false, "required": [ "rate_options" ], "properties": { "rate_options": { "allOf": [ { "$ref": "#/components/schemas/rate_request_body" } ], "description": "The rate options" }, "shipment_ids": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "shipment ids" }, "description": "The array of shipment IDs" }, "shipments": { "type": "array", "minItems": 1, "items": { "allOf": [ { "$ref": "#/components/schemas/address_validating_shipment" } ], "description": "The shipment to get a bulk rate estimate for" }, "description": "The array of shipments to get bulk rate estimates for" }, "ship_to_service_point_id": { "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": { "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" } } }, "compare_bulk_rates_response_body": { "title": "compare_bulk_rates_response_body", "type": "array", "description": "A bulk rate response body", "items": { "$ref": "#/components/schemas/bulk_rate" } }, "create_combined_label_document_request_body": { "title": "create_combined_label_document_request_body", "type": "object", "description": "A create combined label document request body", "additionalProperties": false, "properties": { "label_ids": { "type": "array", "items": { "$ref": "#/components/schemas/se_id" }, "description": "The list of up to 30 label IDs to include in the combined label document.\nNote that to avoid response size limits, you should only expect to be able to combine 30 single page labels similar in size to that of USPS labels.\n" }, "label_format": { "enum": [ "pdf" ], "type": "string", "example": "pdf", "description": "The file format for the combined label document; note that currently only `\"pdf\"` is supported." }, "label_download_type": { "default": "inline", "allOf": [ { "$ref": "#/components/schemas/label_download_type" } ] } } }, "create_combined_label_document_response_body": { "title": "create_combined_label_document_response_body", "type": "object", "description": "A create combined label document response body", "additionalProperties": false, "properties": { "label_download": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/label_download" } ], "description": "The download for the combined label document" } } }, "document_type": { "title": "document_type", "type": "string", "description": "The type of carrier document being registered. Supported values vary by carrier. See the [Carrier Document Upload guide](/upload-carrier-documents) for the document types each carrier accepts.\n", "enum": [ "commercial_invoice", "certificate_of_origin", "usmca_commercial_invoice_certification_of_origin", "usmca_certification_of_origin", "pro_forma_invoice", "other", "authorization_form", "export_accompanying_document", "export_license", "import_permit", "one_time_nafta", "power_of_attorney", "packing_list", "sed_document", "shippers_letter_of_instruction", "declaration", "section_232_customs_affidavit" ], "example": "usmca_commercial_invoice_certification_of_origin" }, "document_format": { "title": "document_format", "type": "string", "description": "The file format of the document being uploaded.", "enum": [ "PDF", "PNG" ], "example": "PDF" }, "document_status_value": { "title": "document_status_value", "type": "string", "description": "The processing status of a carrier document.\n\n- `awaiting_upload` - The document has been registered and is waiting for the file to be uploaded to the provided upload target.\n- `processing` - The uploaded file is being processed.\n- `processing_claimed` - The document has been claimed for processing.\n- `invalid` - The document failed validation and cannot be used.\n- `uploaded` - The file has been uploaded successfully and is ready to be sent to the carrier.\n- `queued` - The document is queued to be sent to the carrier.\n- `sent` - The document has been transmitted to the carrier.\n- `failed` - Sending the document to the carrier failed.\n", "enum": [ "awaiting_upload", "processing", "processing_claimed", "invalid", "uploaded", "queued", "sent", "failed" ], "example": "awaiting_upload" }, "register_document_request_body": { "title": "register_document_request_body", "type": "object", "description": "A request to register a carrier document against a shipment or label.", "additionalProperties": false, "required": [ "type", "file_name" ], "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/document_type" } ], "description": "The type of document being registered." }, "format": { "allOf": [ { "$ref": "#/components/schemas/document_format" } ], "description": "The file format of the document. Defaults to `PDF` when omitted." }, "file_name": { "type": "string", "description": "The file name of the document, including its extension.", "example": "usmca-certification-of-origin.pdf" } } }, "register_document_response_body": { "title": "register_document_response_body", "type": "object", "description": "The result of registering a document. Use the returned `upload` target to upload the document file to Amazon S3 before sending it to the carrier.\n", "additionalProperties": false, "properties": { "document_id": { "type": "string", "description": "The unique identifier assigned to the registered document.", "example": "019eb24e-cd4e-7609-b740-c2324fe93272" }, "upload": { "allOf": [ { "$ref": "#/components/schemas/document_upload_target" } ], "description": "The pre-signed Amazon S3 target the document file must be uploaded to.\n" } }, "example": { "document_id": "019eb24e-cd4e-7609-b740-c2324fe93272", "upload": { "url": "https://carrier-doc-upload.s3.amazonaws.com", "fields": { "Content-Type": "application/pdf", "key": "019eb24e-cd4e-7609-b740-c2324fe93272.pdf", "x-amz-meta-document-id": "019eb24e-cd4e-7609-b740-c2324fe93272", "x-amz-meta-seller-id": "8801990", "X-Amz-Algorithm": "AWS4-HMAC-SHA256", "X-Amz-Credential": "ASIA.../20260610/us-east-1/s3/aws4_request", "X-Amz-Date": "20260610T161249Z", "Policy": "eyJleHBpcmF0aW9uIjoi...", "X-Amz-Signature": "b81189b9df29...", "X-Amz-Security-Token": "IQoJb3JpZ2lu..." } } } }, "document_upload_target": { "title": "document_upload_target", "type": "object", "description": "A pre-signed Amazon S3 POST target describing where and how to upload a document file.\n", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "description": "The Amazon S3 endpoint to upload the document file to via an HTTP `POST` with `multipart/form-data`.\n", "example": "https://carrier-doc-upload.s3.amazonaws.com" }, "fields": { "type": "object", "description": "The S3 presigned-POST form fields. Include **every** field exactly as returned in the upload request, followed by a `file` part containing the document content.\n", "properties": { "Content-Type": { "type": "string", "description": "The MIME type of the document; matches the registered document format.", "example": "application/pdf" }, "key": { "type": "string", "description": "The S3 object key the file will be stored under.", "example": "019eb24e-cd4e-7609-b740-c2324fe93272.pdf" }, "x-amz-meta-document-id": { "type": "string", "description": "S3 object metadata: the registered document's unique identifier.", "example": "019eb24e-cd4e-7609-b740-c2324fe93272" }, "x-amz-meta-seller-id": { "type": "string", "description": "S3 object metadata: the seller's identifier.", "example": "8801990" }, "X-Amz-Algorithm": { "type": "string", "description": "The AWS signing algorithm used for the pre-signed POST.", "example": "AWS4-HMAC-SHA256" }, "X-Amz-Credential": { "type": "string", "description": "The AWS credential scope used to sign the upload.", "example": "ASIA.../20260610/us-east-1/s3/aws4_request" }, "X-Amz-Date": { "type": "string", "description": "The timestamp the signature was generated, in ISO 8601 basic format.", "example": "20260610T161249Z" }, "Policy": { "type": "string", "description": "The base64-encoded S3 POST policy defining the conditions the upload must satisfy, such as the allowed key, content type, size, and expiration.\n", "example": "eyJleHBpcmF0aW9uIjoi..." }, "X-Amz-Signature": { "type": "string", "description": "The signature authorizing the upload, derived from the policy and credentials.", "example": "b81189b9df29..." }, "X-Amz-Security-Token": { "type": "string", "description": "The temporary AWS session token for the credentials.", "example": "IQoJb3JpZ2lu..." } }, "additionalProperties": { "type": "string" } } } }, "document_status": { "title": "document_status", "type": "object", "description": "The current state of a carrier document.", "additionalProperties": false, "properties": { "document_id": { "type": "string", "description": "The unique identifier of the document.", "example": "7f3c1b2a-9d4e-4f5a-8c6b-2e1d0a9b8c7d" }, "type": { "allOf": [ { "$ref": "#/components/schemas/document_type" } ], "description": "The type of the document." }, "file_name": { "type": "string", "description": "The file name of the document.", "example": "usmca-certification-of-origin.pdf" }, "status": { "allOf": [ { "$ref": "#/components/schemas/document_status_value" } ], "description": "The processing status of the document." }, "error": { "type": [ "string", "null" ], "example": "The uploaded file could not be read.", "description": "A description of the error when the document is `invalid` or `failed`; otherwise `null`." }, "external_id": { "type": [ "string", "null" ], "example": "1Z999AA10123456784", "description": "The carrier-assigned identifier for the document once it has been sent; otherwise `null`." } } }, "list_documents_response_body": { "title": "list_documents_response_body", "type": "array", "description": "The list of documents registered against the shipment or label.", "items": { "$ref": "#/components/schemas/document_status" } }, "order_shipment": { "title": "order_shipment", "type": "object", "description": "A shipment associated with the requested id, along with its registered documents.", "additionalProperties": false, "properties": { "shipment_id": { "type": "string", "description": "The unique identifier of the shipment.", "example": "se-28529731" }, "tracking_number": { "type": "string", "description": "The tracking number of the shipment.", "example": "1Z999AA10123456784" }, "documents": { "type": "array", "description": "The carrier documents registered against the shipment.", "items": { "$ref": "#/components/schemas/document_status" } } } }, "list_shipment_labels_response_body": { "title": "list_shipment_labels_response_body", "type": "array", "description": "The list of shipments associated with the requested id and their registered documents.", "items": { "$ref": "#/components/schemas/order_shipment" } }, "send_documents_response_body": { "title": "send_documents_response_body", "type": "object", "description": "The result of sending a label's documents to the carrier.", "additionalProperties": false, "properties": { "sent_count": { "type": "integer", "description": "The number of documents that were sent to the carrier.", "example": 2 }, "document_ids": { "type": "array", "items": { "type": "string" }, "description": "The identifiers of the documents that were sent." } } }, "link": { "title": "link", "type": "object", "description": "A link to a related resource", "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", "null" ], "minLength": 1, "description": "Additional text about how to handle the shipment at this address.\n", "example": "any instructions" }, "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 assigned 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" } } } } } }, "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", "null" ], "example": "example@example.com", "description": "Email for the address owner.\n" }, "company_name": { "type": [ "string", "null" ], "minLength": 1, "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", "null" ], "minLength": 1, "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", "null" ], "minLength": 1, "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": { "$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", "null" ], "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": { "$ref": "#/components/schemas/date_time" }, "end_at": { "$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": { "title": "pickup_windows", "type": "object", "properties": { "start_at": { "$ref": "#/components/schemas/date_time" }, "end_at": { "$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", "exclusiveMinimum": 0, "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": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/date_time" } ], "description": "When the rate was created" }, "status": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/rate_response_status" } ] }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/error" } } } }, "rate_detail": { "title": "rate_detail", "type": "object", "description": "Represents detailed information about a shipping cost.\n", "additionalProperties": false, "properties": { "rate_detail_type": { "type": "string", "example": "shipping", "description": "The category of charge. Common values include `shipping` and `additional_fees`. DDP shipments (`customs.terms_of_trade_code: \"ddp\"`) also return `prepaid_duties`, `prepaid_taxes` and `prepaid_import_fees` on Wallet carriers, or `estimated_duties`, `estimated_taxes` and `estimated_import_fees` on BYOA (Bring Your Own Account) carriers.\n" }, "carrier_description": { "type": [ "string", "null" ], "example": "Shipping", "description": "The carrier-provided description of the charge." }, "carrier_billing_code": { "type": [ "string", "null" ], "example": "BaseServiceCharge", "description": "The carrier billing code, when provided by the carrier." }, "carrier_memo": { "type": [ "string", "null" ], "example": "", "description": "An optional carrier-supplied note for the charge." }, "amount": { "allOf": [ { "$ref": "#/components/schemas/monetary_value" } ], "description": "The amount of this individual charge." }, "billing_source": { "type": "string", "example": "carrier", "description": "The source that produced the charge. Common values are `carrier` for carrier-billed charges and `dutiestax` for duties and taxes on DDP shipments (prepaid on Wallet carriers, estimated on BYOA carriers).\n" } } }, "rate": { "title": "rate", "type": "object", "description": "A rate", "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_id": { "readOnly": true, "oneOf": [ { "type": "null" }, { "$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", "null" ], "format": "int32", "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", "null" ], "readOnly": true, "minLength": 1, "example": "package", "description": "package type that this rate was estimated for" }, "delivery_days": { "type": [ "integer", "null" ], "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, "oneOf": [ { "$ref": "#/components/schemas/date" }, { "type": "null" } ], "example": "2024-12-23T00:00:00.000Z" }, "carrier_delivery_days": { "type": [ "string", "null" ], "readOnly": true, "minLength": 1, "example": "22", "description": "The carrier delivery days" }, "delivery_prediction": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/delivery_prediction" } ], "description": "ShipStation's predicted estimated delivery date." }, "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" }, "rate_details": { "type": "array", "readOnly": true, "description": "A breakdown of individual charges that make up this rate, such as base shipping cost and additional fees. For DDP shipments it also includes duties, taxes, and import fees (prepaid on Wallet carriers, estimated on BYOA carriers).\n", "items": { "$ref": "#/components/schemas/rate_detail" } }, "carrier_weight": { "readOnly": true, "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/weight" } ], "description": "The billable weight assessed by the carrier, based on the weight and dimensions submitted with the rate request." }, "display_scheme": { "readOnly": true, "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/display_scheme_response" } ], "description": "The display format for the label this rate would produce." } } }, "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": { "$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" }, "send_rates": { "type": "boolean", "readOnly": true, "description": "The service provides rates for the shipment.", "example": true } } }, "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": { "$ref": "#/components/schemas/address_validation_status" }, "original_address": { "allOf": [ { "$ref": "#/components/schemas/address" } ], "description": "The original address that was sent for validation" }, "matched_address": { "readOnly": true, "oneOf": [ { "$ref": "#/components/schemas/address" }, { "type": "null" } ], "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": { "oneOf": [ { "$ref": "#/components/schemas/address_validation_detail_code" }, { "type": "null" } ] } } }, "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": { "$ref": "#/components/schemas/label_messages" }, "external_package_id": { "type": "string", "minLength": 1, "description": "An external package id.", "example": "se-1234567" }, "content_description": { "type": [ "string", "null" ], "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" }, "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": { "$ref": "#/components/schemas/label_messages" }, "external_package_id": { "type": "string", "minLength": 1, "description": "An external package id.", "example": "se-1234545" }, "content_description": { "type": [ "string", "null" ], "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" }, "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", "null" ], "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", "null" ], "default": null, "example": "3926.10", "description": "The [Harmonized Tariff Code](https://en.wikipedia.org/wiki/Harmonized_System) of this item." }, "country_of_origin": { "default": null, "oneOf": [ { "$ref": "#/components/schemas/country_code" }, { "type": "null" } ], "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", "null" ], "example": "pound" }, "sku": { "type": [ "string", "null" ], "description": "The SKU (Stock Keeping Unit) of the item", "example": "sku-1223344" }, "sku_description": { "type": [ "string", "null" ], "description": "Description of the Custom Item's SKU", "example": "this is a description" }, "mid_code": { "type": [ "string", "null" ], "description": "Manufacturers Identification code", "example": "GBCOM15BRI" }, "product_url": { "type": [ "string", "null" ], "description": "link to the item on the seller website", "example": "https://myproduct.com" }, "vat_rate": { "type": [ "number", "null" ], "description": "VAT rate applicable to the item", "example": 0.2 }, "dangerous_goods": { "type": "array", "default": [], "minItems": 0, "description": "Details about dangerous goods inside products", "items": { "$ref": "#/components/schemas/dangerous_goods" } }, "manufacturer_product_id_type": { "default": null, "oneOf": [ { "$ref": "#/components/schemas/manufacturer_product_identifier_type" }, { "type": "null" } ], "description": "The type of identifier used for the manufacturer product ID.", "example": "gtin" }, "manufacturer_product_id": { "type": [ "string", "null" ], "default": null, "description": "The manufacturer's product identifier corresponding to the `manufacturer_product_id_type`.", "example": "012345678905" }, "manufacturer_ns_product_id": { "type": [ "string", "null" ], "default": null, "description": "A non-standardized product identifier unique to the manufacturer's own system that does not follow an internationally recognized standard (e.g. a SKU).", "example": "MY-SKU-12345" }, "cpsc_certificates": { "type": [ "array", "null" ], "default": null, "description": "List of CPSC eFiling certificates associated with this product.", "items": { "$ref": "#/components/schemas/cpsc_certificate" } }, "cpsc_disclaim": { "type": [ "object", "null" ], "default": null, "description": "CPSC disclaimer information for products that do not require a Certificate of Compliance, even though their HTS code is flagged as potentially subject to CPSC regulation. Use either `cpsc_certificates` or `cpsc_disclaim` per product, not both.", "required": [ "disclaim_code", "intended_use_code" ], "properties": { "disclaim_code": { "type": "string", "enum": [ "A", "B" ], "description": "The CPSC disclaimer code indicating why no certificate is required. `A` - Product Not Regulated by CPSC: product falls outside CPSC jurisdiction (e.g., regulated by FDA), has no applicable CPSC safety standard, or is a B2B part for further assembly. `B` - Enforcement Discretion: product falls under CPSC jurisdiction and a rule technically applies, but CPSC is exercising enforcement discretion and does not require a certificate.\n", "example": "B" }, "intended_use_code": { "type": "string", "maxLength": 16, "description": "A code from CBP's Intended Use Code list indicating why the product is exempt. Required for every Disclaim filing. For Disclaim B, must be `130.006`. For Disclaim A, valid base codes are: `081.XXX` (Medical Device), `090.XXX` (Military Use), `100.XXX` (Personal Use), `130.XXX` (Consumer Use), `155.XXX` (Commercial Assembly), `970.XXX` (Export), `980.000` (Other Use - `intended_use_description` recommended).\n", "example": "130.006" }, "intended_use_description": { "type": [ "string", "null" ], "default": null, "maxLength": 100, "description": "A plain-language description of the product's intended use. Max 100 characters. Recommended by CPSC when `intended_use_code` is `980.000` (Other Use).\n", "example": "" } } } } } } } }, "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", "null" ], "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", "null" ], "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", "null" ], "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", "exclusiveMinimum": 0, "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", "null" ], "default": null, "description": "UN number to identify the dangerous goods.", "example": "1234r1" }, "shipping_name": { "type": [ "string", "null" ], "default": null, "description": "Trade description of the dangerous goods.", "example": "things with dangerous goods" }, "technical_name": { "type": [ "string", "null" ], "default": null, "description": "Recognized Technical or chemical name of dangerous goods.", "example": "chloric acid" }, "product_class": { "type": [ "string", "null" ], "default": null, "description": "Dangerous goods product class based on regulation.", "example": "1987" }, "product_class_subsidiary": { "type": [ "string", "null" ], "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", "null" ], "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", "null" ], "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", "null" ], "default": null, "description": "Transport category assign to dangerous goods for the transport purpose.", "example": "6.1" }, "regulation_authority": { "type": [ "string", "null" ], "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", "null" ], "example": false, "description": "Indication if the substance is radioactive." }, "reportable_quantity": { "type": [ "boolean", "null" ], "example": false, "description": "Indication if the substance needs to be reported to regulatory authority based on the quantity." }, "tunnel_code": { "type": [ "string", "null" ], "default": null, "description": "Defines which types of tunnels the shipment is allowed to go through", "example": "all" }, "additional_description": { "type": [ "string", "null" ], "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", "null" ], "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", "null" ], "default": null, "description": "The instructions for the paperless download.\n", "example": "any instructions" }, "handoff_code": { "type": [ "string", "null" ], "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", "null" ], "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": { "default": null, "oneOf": [ { "$ref": "#/components/schemas/country_code" }, { "type": "null" } ], "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": { "default": null, "oneOf": [ { "$ref": "#/components/schemas/bill_to_party" }, { "type": "null" } ], "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", "null" ], "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": { "oneOf": [ { "$ref": "#/components/schemas/weight" }, { "type": "null" } ], "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", "null" ], "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", "null" ], "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", "null" ], "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", "null" ], "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", "null" ], "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": { "default": null, "oneOf": [ { "$ref": "#/components/schemas/origin_type" }, { "type": "null" } ] }, "additional_handling": { "type": [ "boolean", "null" ], "default": null, "description": "Indicate to the carrier that this shipment requires additional handling.\n", "example": true }, "shipper_release": { "type": [ "boolean", "null" ], "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": { "$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" } } }, "movement_indicator": { "type": [ "string", "null" ], "default": null, "description": "An indicator that will tell the carrier the type of movement for the shipment.", "example": "b2b", "enum": [ "c2c", "b2c", "c2b", "b2b" ] }, "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", "deprecated": true, "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", "null" ], "description": "Ancillary endorsements option for the shipment", "example": "forward" }, "return_pickup_attempts": { "type": [ "integer", "null" ], "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": { "default": null, "oneOf": [ { "$ref": "#/components/schemas/regulated_content_type" }, { "type": "null" } ], "description": "Indicates the category of goods in the shipment that is subject to special regulatory or compliance requirements" }, "netstamps_options": { "type": "object", "description": "Layout options for printing NetStamps labels on a sheet. Controls the starting position on the label sheet.", "properties": { "row": { "type": "integer", "format": "int32", "description": "The row on the sheet where label is placed.", "example": 1 }, "column": { "type": "integer", "format": "int32", "description": "The column on the sheet where label is placed.", "example": 1 } } }, "suppress_carrier_generated_documents": { "type": "array", "description": "A list of carrier-generated documents to suppress for the shipment.\n\n> **Note:** Currently, only `commercial_invoice` is supported (UPS only).\n", "items": { "type": "string", "enum": [ "commercial_invoice" ] }, "example": [ "commercial_invoice" ] }, "transparency_codes": { "type": "array", "description": "Amazon Transparency Codes for verifying product authenticity. Each entry maps transparency codes to the corresponding order item ID, which must match the value in `shipment.items[].external_order_item_id`.\n", "items": { "type": "object", "properties": { "order_item_id": { "type": "string", "description": "The order item ID from Amazon, matching the `external_order_item_id` in the shipment items.", "example": "12345678901234" }, "codes": { "type": "array", "description": "Array of Amazon Transparency codes for this order item.", "items": { "type": "string", "example": "AZ:XXXXXXXXXXXX" } } }, "required": [ "order_item_id", "codes" ] } } } }, "international_shipment_options": { "title": "international_shipment_options", "type": "object", "description": "Options for international shipments, such as customs declarations.", "required": [ "contents", "non_delivery" ], "additionalProperties": false, "example": { "terms_of_trade_code": "ddp", "contents": "gift", "non_delivery": "return_to_sender" }, "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" }, "pending_documents": { "type": "boolean", "default": false, "description": "Set to `true` to indicate the shipment requires customs documents to be uploaded via Carrier Document Upload. See the [Carrier Document Upload guide](/upload-carrier-documents).\n", "example": true }, "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", "null" ], "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", "null" ], "default": null, "example": "3926.10", "description": "The [Harmonized Tariff Code](https://en.wikipedia.org/wiki/Harmonized_System) of this item." }, "country_of_origin": { "default": null, "oneOf": [ { "$ref": "#/components/schemas/country_code" }, { "type": "null" } ], "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", "null" ], "example": "pound" }, "sku": { "type": [ "string", "null" ], "description": "The SKU (Stock Keeping Unit) of the customs item", "example": "sku-1234" }, "sku_description": { "type": [ "string", "null" ], "description": "Description of the Custom Item's SKU", "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", "null" ], "example": "example@example.com", "description": "Email for the address owner.\n" }, "company_name": { "type": [ "string", "null" ], "minLength": 1, "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", "null" ], "minLength": 1, "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", "null" ], "minLength": 1, "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": { "$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", "null" ], "minLength": 1, "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 assigned 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": { "$ref": "#/components/schemas/taxable_entity_type" }, "identifier_type": { "$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", "null" ], "description": "The ID of the sales order that this item belongs to. In shipment responses, this is `null` if the\nitem isn't linked to a sales order.\n", "example": "8c1f2a5e-3b7d-4e9a-a6c2-1d4f5e6a7b8c" }, "sales_order_item_id": { "type": [ "string", "null" ], "description": "The ID of the sales order line item that this item belongs to. In shipment responses, this is\n`null` if the item isn't linked to a sales order.\n", "example": "2e7b9c4d-6a1f-4c3e-8b5d-9f0a1b2c3d4e" }, "quantity": { "type": "integer", "format": "int32", "minimum": 0, "description": "The quantity of this item included in the shipment", "example": 1 }, "sku": { "type": [ "string", "null" ], "description": "Item Stock Keeping Unit", "example": "sku-1234" }, "bundle_sku": { "type": [ "string", "null" ], "description": "Bundle SKU for the item", "example": "bundle-123" }, "external_order_id": { "type": [ "string", "null" ], "description": "external order id", "example": "123445" }, "external_order_item_id": { "type": [ "string", "null" ], "description": "external order item id", "example": "12" }, "asin": { "type": [ "string", "null" ], "minLength": 10, "maxLength": 10, "example": "B00005N5PF", "description": "Amazon Standard Identification Number" }, "order_source_code": { "$ref": "#/components/schemas/order_source_name" }, "item_id": { "type": [ "string", "null" ], "description": "Unique identifier for the item. Use this value as `item_id` when you\n[split a shipment](#operation/split_shipment).\n", "example": "1402291169813" }, "allocation_status": { "type": [ "string", "null" ], "description": "Allocation status of the item", "example": "allocated" }, "image_url": { "type": [ "string", "null" ], "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", "null" ], "minimum": 0, "description": "Unit price of the item", "example": 88 }, "tax_amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Tax amount for the item", "example": 5.5 }, "shipping_amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Shipping amount for the item", "example": 10 }, "inventory_location": { "type": [ "string", "null" ], "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", "null" ], "description": "Product ID", "example": "10408926" }, "fullfilment_sku": { "type": [ "string", "null" ], "description": "Fulfillment SKU", "example": "fulfill-123" }, "upc": { "type": [ "string", "null" ], "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", "null" ], "readOnly": 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, "oneOf": [ { "$ref": "#/components/schemas/se_id" }, { "type": "null" } ], "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": { "$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": { "$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": { "$ref": "#/components/schemas/date_time" }, "actual_delivery_date": { "$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": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/tracking_status_code" } ], "example": "IT" }, "status_detail_code": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/tracking_status_detail_code" } ], "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": { "$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": { "$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": { "$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": { "$ref": "#/components/schemas/error_source" }, "error_type": { "$ref": "#/components/schemas/error_type" }, "error_code": { "$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": { "$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": { "$ref": "#/components/schemas/error_source" }, "error_type": { "$ref": "#/components/schemas/error_type" }, "error_code": { "$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" } ] }, "create_tag_request_body": { "title": "create_tag_request_body", "type": "object", "description": "A create tag request body", "required": [ "name" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "example": "Fragile", "description": "The tag name." }, "color": { "type": "string", "minLength": 1, "example": "#FF0000", "description": "A hex-coded string identifying the color of the tag." } } }, "create_warehouse_request_body": { "title": "create_warehouse_request_body", "description": "A create warehouse request body", "required": [ "name", "origin_address" ], "additionalProperties": false, "allOf": [ { "$ref": "#/components/schemas/warehouse" } ] }, "create_warehouse_response_body": { "title": "create_warehouse_response_body", "description": "A create warehouse response body", "required": [ "warehouse_id", "name", "created_at", "origin_address", "return_address" ], "additionalProperties": false, "allOf": [ { "$ref": "#/components/schemas/warehouse" } ] }, "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": { "$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": "Get shipment tags response body", "required": [ "tags" ], "additionalProperties": false, "properties": { "tags": { "type": "array", "items": { "$ref": "#/components/schemas/tag_name" } } } }, "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" } ] }, "get_service_point_by_id_response_body": { "title": "get_service_point_by_id_response_body", "type": "object", "description": "A get service point by ID response body", "properties": { "service_point": { "type": "object", "properties": { "carrier_code": { "$ref": "#/components/schemas/carrier_code" }, "service_codes": { "type": "array", "items": { "type": "string", "description": "A shipping carrier service code." } }, "service_point_id": { "type": "string", "example": "614940", "description": "A unique identifier for a carrier drop off point." }, "company_name": { "type": "string", "example": "My fancy company name", "description": "If this is a business address, then the company name should be specified here." }, "address_line1": { "type": "string", "example": "PLACE DU CANADA", "description": "The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines." }, "city_locality": { "type": "string", "example": "TRUN", "description": "The name of the city or locality" }, "state_province": { "type": "string", "example": "TRUN", "description": "The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation." }, "postal_code": { "$ref": "#/components/schemas/postal_code" }, "country_code": { "$ref": "#/components/schemas/country_code" }, "phone_number": { "type": "string", "example": "555-555-5555", "description": "Phone number associated" }, "lat": { "format": "double", "type": "number", "example": 48.842608, "description": "The latitude of the point. Represented as signed degrees. Required if long is provided. http://www.geomidpoint.com/latlon.html" }, "long": { "format": "double", "type": "number", "example": 0.032875, "description": "The longitude of the point. Represented as signed degrees. Required if lat is provided. http://www.geomidpoint.com/latlon.html" }, "hours_of_operation": { "type": "object", "description": "Hours of operation", "properties": { "monday": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "example": "09:15", "description": "Opening time" }, "close": { "type": "string", "example": "12:00", "description": "Closing time" } } } }, "tuesday": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "example": "09:15", "description": "Opening time" }, "close": { "type": "string", "example": "12:00", "description": "Closing time" } } } }, "wednesday": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "example": "09:15", "description": "Opening time" }, "close": { "type": "string", "example": "12:00", "description": "Closing time" } } } }, "thursday": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "example": "09:15", "description": "Opening time" }, "close": { "type": "string", "example": "12:00", "description": "Closing time" } } } }, "friday": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "example": "09:15", "description": "Opening time" }, "close": { "type": "string", "example": "12:00", "description": "Closing time" } } } }, "saturday": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "example": "09:15", "description": "Opening time" }, "close": { "type": "string", "example": "12:00", "description": "Closing time" } } } }, "sunday": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "example": "09:15", "description": "Opening time" }, "close": { "type": "string", "example": "12:00", "description": "Closing time" } } } } } }, "features": { "type": "array", "description": "Service features", "items": { "type": "string", "enum": [ "drop_off_point", "pickup_point", "print_services", "after_hours_locker", "after_hours_dropbox" ] } }, "type": { "type": "string", "example": "pudo", "description": "Service point type", "default": "pudo", "enum": [ "pudo", "locker" ] } } } } }, "get_service_points_request": { "title": "get_service_points_request", "oneOf": [ { "$ref": "#/components/schemas/get_service_points_request_body" } ] }, "get_service_points_request_body": { "title": "get_service_points_request_body", "type": "object", "description": "A get service points request body. Caller must provide exactly one of address_query, address, or lat / long pair.", "required": [ "providers" ], "properties": { "address_query": { "type": "string", "description": "Unstructured text to search for service points by.", "example": "177A Bleecker Street New York" }, "address": { "type": "object", "description": "Structured address to search by.", "required": [ "country_code" ], "properties": { "address_line1": { "type": "string", "example": "1999 Bishop Grandin Blvd.", "description": "The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines." }, "address_line2": { "type": "string", "example": "Unit 408" }, "address_line3": { "type": "string", "example": "Building #7" }, "city_locality": { "type": "string", "example": "Winnipeg", "description": "The name of the city or locality" }, "state_province": { "type": "string", "example": "Manitoba", "description": "The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation." }, "postal_code": { "$ref": "#/components/schemas/postal_code" }, "country_code": { "$ref": "#/components/schemas/country_code" } } }, "providers": { "type": "array", "description": "An array of shipping service providers and service codes", "items": { "type": "object", "properties": { "carrier_id": { "type": "string", "example": "se-123456", "description": "Uniquely identifies a carrier connection" }, "service_code": { "type": "array", "items": { "type": "string", "example": "chronoclassic", "description": "Uniquely identifies a shipping service" } } } } }, "lat": { "format": "double", "type": "number", "example": 48.874518928233094, "description": "The latitude of the point. Represented as signed degrees. Required if long is provided. http://www.geomidpoint.com/latlon.html" }, "long": { "format": "double", "type": "number", "example": 2.3591775711639404, "description": "The longitude of the point. Represented as signed degrees. Required if lat is provided. http://www.geomidpoint.com/latlon.html" }, "radius": { "format": "int32", "type": "integer", "example": 500, "description": "Search radius in kilometers" }, "max_results": { "format": "int32", "type": "integer", "example": 25, "description": "The maximum number of service points to return" }, "shipment": { "type": "object", "description": "Shipment information to be used for service point selection", "properties": { "total_weight": { "allOf": [ { "$ref": "#/components/schemas/weight" } ], "description": "Shipment total weight" }, "packages": { "type": "array", "description": "An array of package dimensions", "items": { "type": "object", "properties": { "dimensions": { "allOf": [ { "$ref": "#/components/schemas/dimensions" } ], "description": "The package dimensions" } } } } } } } }, "get_tracking_log_response_body": { "title": "get_tracking_log_response_body", "description": "A get tracking log response body", "required": [ "tracking_number", "tracking_url", "status_code", "carrier_code", "carrier_id", "carrier_detail_code", "carrier_status_code", "events" ], "additionalProperties": false, "allOf": [ { "$ref": "#/components/schemas/tracking_information" } ] }, "list_service_points_response_body": { "title": "list_service_points_response_body", "type": "object", "description": "A list service points response body", "properties": { "lat": { "format": "double", "type": "number", "example": 48.842608, "description": "The latitude of the point. Represented as signed degrees. Required if long is provided. http://www.geomidpoint.com/latlon.html" }, "long": { "format": "double", "type": "number", "example": 0.032875, "description": "The longitude of the point. Represented as signed degrees. Required if lat is provided. http://www.geomidpoint.com/latlon.html" }, "service_points": { "type": "array", "items": { "type": "object", "properties": { "carrier_code": { "$ref": "#/components/schemas/carrier_code" }, "service_codes": { "type": "array", "items": { "type": "string", "example": "chronoclassic", "description": "A shipping carrier service code." } }, "service_point_id": { "type": "string", "example": "614940", "description": "A unique identifier for a carrier drop off point." }, "company_name": { "type": "string", "example": "My fancy company name", "description": "If this is a business address, then the company name should be specified here." }, "address_line1": { "type": "string", "example": "PLACE DU CANADA", "description": "The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines." }, "city_locality": { "type": "string", "example": "TRUN", "description": "The name of the city or locality" }, "state_province": { "type": "string", "example": "TRUN", "description": "The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation." }, "postal_code": { "$ref": "#/components/schemas/postal_code" }, "country_code": { "$ref": "#/components/schemas/country_code" }, "phone_number": { "type": "string", "example": "555-555-5555", "description": "Phone number associated" }, "lat": { "format": "double", "type": "number", "example": 48.842608, "description": "The latitude of the point. Represented as signed degrees. Required if long is provided. http://www.geomidpoint.com/latlon.html" }, "long": { "format": "double", "type": "number", "example": 0.032875, "description": "The longitude of the point. Represented as signed degrees. Required if lat is provided. http://www.geomidpoint.com/latlon.html" }, "distance_in_meters": { "format": "double", "type": "number", "example": 728.9959308847579, "description": "Distance in meters" }, "hours_of_operation": { "type": "object", "description": "Hours of operation", "properties": { "monday": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "example": "09:15", "description": "Opening time" }, "close": { "type": "string", "example": "12:00", "description": "Closing time" } } } }, "tuesday": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "example": "09:15", "description": "Opening time" }, "close": { "type": "string", "example": "12:00", "description": "Closing time" } } } }, "wednesday": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "example": "09:15", "description": "Opening time" }, "close": { "type": "string", "example": "12:00", "description": "Closing time" } } } }, "thursday": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "example": "09:15", "description": "Opening time" }, "close": { "type": "string", "example": "12:00", "description": "Closing time" } } } }, "friday": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "example": "09:15", "description": "Opening time" }, "close": { "type": "string", "example": "12:00", "description": "Closing time" } } } }, "saturday": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "example": "09:15", "description": "Opening time" }, "close": { "type": "string", "example": "12:00", "description": "Closing time" } } } }, "sunday": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "example": "09:15", "description": "Opening time" }, "close": { "type": "string", "example": "12:00", "description": "Closing time" } } } } } }, "features": { "type": "array", "description": "Service features", "items": { "type": "string", "enum": [ "drop_off_point", "pickup_point", "print_services", "after_hours_locker", "after_hours_dropbox" ] } }, "type": { "type": "string", "example": "pudo", "description": "Service point type", "default": "pudo", "enum": [ "pudo", "locker" ] } } } }, "errors": { "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/error" }, "description": "The errors associated with the failed API call" } } }, "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": { "$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" ], "allOf": [ { "$ref": "#/components/schemas/partial_shipment" }, { "title": "rate_response", "type": "object", "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": { "$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": { "$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, "example": { "approved": false, "message": "Unable to delete FedEx shipment. Unable to retrieve record from database.", "reason_code": "label_not_found_within_void_period" }, "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." }, "voided_label_ids": { "readOnly": true, "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "The Ids of any associated labels that were also voided as part of this request. Includes the originally requested label." }, "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" } ] }, "get_label_by_external_shipment_id_response_body": { "title": "get_label_by_external_shipment_id_response_body", "type": "object", "description": "A get label by external shipment id response body", "additionalProperties": false, "allOf": [ { "$ref": "#/components/schemas/label" } ] }, "create_label_from_rate_response_body": { "title": "create_label_from_rate_response_body", "type": "object", "description": "A create label from rate response body", "allOf": [ { "$ref": "#/components/schemas/label" } ] }, "create_label_response_body": { "title": "create_label_response_body", "type": "object", "description": "A create label response body", "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": { "$ref": "#/components/schemas/rate_shopper_strategy" } } }, "rate_shopper_strategy": { "title": "rate_shopper_strategy", "type": "string", "readOnly": true, "description": "The Rate Shopper strategy used to create this label", "example": "cheapest", "enum": [ "cheapest", "fastest", "best_value" ] }, "rate_shopper_list_response_body": { "title": "rate_shopper_list_response_body", "type": "object", "description": "A list of rate shoppers (both default and custom) for the authenticated seller.", "additionalProperties": false, "required": [ "rate_shoppers" ], "properties": { "rate_shoppers": { "type": "array", "description": "The list of rate shoppers. Default rate shoppers appear first, followed by custom ones.", "items": { "$ref": "#/components/schemas/rate_shopper_response" } } } }, "rate_shopper_response": { "title": "rate_shopper_response", "type": "object", "description": "A rate shopper configuration. Can be a default rate shopper (cheapest,\nfastest, best_value) or a seller-created custom rate shopper.\n", "additionalProperties": false, "required": [ "rate_shopper_id", "name", "services", "is_active", "created_at", "updated_at" ], "properties": { "rate_shopper_id": { "type": "string", "description": "Identifier for the rate shopper. For default rate shoppers this is\na strategy name (`cheapest`, `fastest`, `best_value`). For custom\nrate shoppers this is a UUID.\n", "examples": [ "cheapest", "fastest", "best_value", "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "name": { "type": "string", "description": "Display name of the rate shopper.", "example": "Cheapest" }, "services": { "type": "array", "description": "The carrier services included in this rate shopper.", "items": { "$ref": "#/components/schemas/rate_shopper_service" } }, "transit_time": { "$ref": "#/components/schemas/rate_shopper_transit_time" }, "service_preference": { "$ref": "#/components/schemas/rate_shopper_service_preference" }, "is_active": { "type": "boolean", "description": "Whether the rate shopper is currently active.", "example": true }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the rate shopper was created.", "example": "2025-01-15T10:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the rate shopper was last updated.", "example": "2025-03-20T14:45:00Z" } } }, "rate_shopper_service": { "title": "rate_shopper_service", "type": "object", "description": "A carrier service entry in a rate shopper.", "additionalProperties": false, "required": [ "service_code", "carrier_id" ], "properties": { "service_code": { "type": "string", "description": "The carrier service code.", "example": "usps_priority_mail" }, "carrier_id": { "type": "string", "description": "The carrier account ID (prefixed with `se-`).", "example": "se-28529731" } } }, "rate_shopper_transit_time": { "title": "rate_shopper_transit_time", "type": "object", "description": "Transit time constraints for rate selection.", "additionalProperties": false, "properties": { "max_days": { "type": [ "integer", "null" ], "description": "Maximum transit days for domestic shipments.", "example": 5 }, "max_days_international": { "type": [ "integer", "null" ], "description": "Maximum transit days for international shipments.", "example": 14 }, "use_deliver_by_date": { "type": "boolean", "description": "Whether to use the order's deliver-by date for filtering.", "example": false } } }, "rate_shopper_service_preference": { "title": "rate_shopper_service_preference", "type": "object", "description": "Preferred service and price tolerance settings.", "additionalProperties": false, "properties": { "service": { "$ref": "#/components/schemas/rate_shopper_service" }, "price_tolerance": { "$ref": "#/components/schemas/rate_shopper_price_tolerance" } } }, "rate_shopper_price_tolerance": { "title": "rate_shopper_price_tolerance", "type": "object", "description": "Price tolerance thresholds for the preferred service.", "additionalProperties": false, "required": [ "amount", "percentage" ], "properties": { "amount": { "type": "number", "format": "decimal", "description": "Maximum absolute price difference allowed.", "example": 2.5 }, "percentage": { "type": "number", "format": "decimal", "description": "Maximum percentage price difference allowed.", "example": 10 } } }, "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/carrier_provided_package_type" } ], "description": "Carrier package type items" }, "description": "An array of carrier-provided 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": { "$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", "required": [ "carriers" ], "properties": { "carriers": { "type": "array", "readOnly": true, "items": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/carrier" } ] }, "description": "The carrier response body" } }, "allOf": [ { "$ref": "#/components/schemas/paged_list_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`
`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", "e_commerce_goods", "commercial_sale_of_goods_b2b", "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", "description": "The Incoterms code (terms of trade) for the shipment.\n\nSet to `ddp` to prepay duties and taxes: indicates that the shipper is paying the international delivery duties for this shipment. This option is currently supported by UPS, FedEx, and DHL Express.\n", "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" }, "redirect": { "title": "redirect", "type": "string", "enum": [ "shipengine-dashboard" ], "description": "The resource to return a redirect URL to." }, "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", "bring_your_own_label_not_supported", "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", "multiple_sales_orders", "order_source_not_active", "rate_limit_exceeded", "refresh_not_supported", "request_body_required", "return_label_not_supported", "sales_order_link_required", "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", "freight_connection_inactive", "freight_provider_id_required", "freight_shipment_not_found", "freight_tracking_not_available", "freight_tracking_not_found", "freight_shipment_not_batchable", "freight_provider_already_connected" ], "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", "shipengine" ], "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, the ShipStation API itself, or the underlying ShipEngine platform.\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", "quick" ], "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, "oneOf": [ { "$ref": "#/components/schemas/monetary_value" }, { "type": "null" } ], "description": "The amount that was originally paid for the label" }, "amount_requested": { "readOnly": true, "oneOf": [ { "$ref": "#/components/schemas/monetary_value" }, { "type": "null" } ], "description": "The amount requested to be refunded" }, "amount_approved": { "readOnly": true, "oneOf": [ { "$ref": "#/components/schemas/monetary_value" }, { "type": "null" } ], "description": "The amount approved for refund by the carrier" }, "amount_credited": { "readOnly": true, "oneOf": [ { "$ref": "#/components/schemas/monetary_value" }, { "type": "null" } ], "description": "The amount that has been credited back to the account" } } }, "insurance_provider": { "title": "insurance_provider", "type": "string", "enum": [ "none", "shipsurance", "parcelguard", "xcover", "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." }, "display_scheme_response": { "title": "display_scheme_response", "type": "string", "enum": [ "label", "qr_code", "label_and_qr_code", "paperless", "label_and_paperless", "no_box_no_label" ], "description": "The display format produced for a shipment. This is the full set of values the API can return. The values accepted when *requesting* a label are documented on `display_scheme`." }, "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", "adult_signature_restricted_delivery", "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", "freight_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." }, "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": "https://example.com/resource", "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_rate": { "title": "bulk_rate", "type": "object", "description": "A bulk rate", "required": [ "rate_request_id", "shipment_id", "created_at", "status", "errors" ], "additionalProperties": false, "properties": { "rate_request_id": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "A string that uniquely identifies the rate request" }, "shipment_id": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "A string that uniquely identifies the shipment" }, "created_at": { "format": "date-time", "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/date_time" } ] }, "status": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/rate_response_status" } ] }, "errors": { "type": "array", "readOnly": true, "items": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/error" } ], "description": "An error that occurred while retrieving the bulk rate" }, "description": "An array of errors that were returned while retrieving the bulk rate" } } }, "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" } } }, "tokens_get_ephemeral_token_response_body": { "title": "tokens_get_ephemeral_token_response_body", "type": "object", "properties": { "token": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ", "description": "The requested token that expires in 10 seconds." }, "redirect_url": { "type": "string", "example": "https://app.shipstation.com/oauth/callback?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9", "description": "The redirect url formatted with the requested token." } } }, "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/station/events", "description": "The webhook payload listener URL that you intend to target for webhook dispatches" }, "headers": { "type": "array", "items": { "$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": { "$ref": "#/components/schemas/webhook_event" }, "url": { "allOf": [ { "$ref": "#/components/schemas/url" } ], "example": "https://example.com/station/events", "description": "The webhook payload listener URL that you intend to target for webhook dispatches" }, "headers": { "type": "array", "items": { "$ref": "#/components/schemas/webhook_header" }, "description": "Array of custom webhook headers" }, "store_id": { "type": "integer", "description": "Store ID", "example": 123456 } } }, "rate_estimate_options": { "title": "rate_estimate_options", "type": "object", "description": "The fields shared by every rate estimate request", "additionalProperties": false, "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" ], "properties": { "from_country_code": { "$ref": "#/components/schemas/country_code" }, "from_postal_code": { "$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": { "$ref": "#/components/schemas/country_code" }, "to_postal_code": { "$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": { "$ref": "#/components/schemas/delivery_confirmation" }, "address_residential_indicator": { "$ref": "#/components/schemas/address_residential_indicator" }, "ship_date": { "allOf": [ { "$ref": "#/components/schemas/date_time" } ], "description": "ship date" } } }, "rate_estimate_by_carrier_id": { "title": "rate_estimate_by_carrier_id", "type": "object", "description": "Identifies a single carrier to estimate rates for", "additionalProperties": false, "required": [ "carrier_id" ], "properties": { "carrier_id": { "deprecated": true, "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "A string that uniquely identifies the carrier", "example": "se-1234567" } } }, "rate_estimate_by_carrier_ids": { "title": "rate_estimate_by_carrier_ids", "type": "object", "description": "Identifies the carriers to estimate rates for", "additionalProperties": false, "required": [ "carrier_ids" ], "properties": { "carrier_ids": { "type": "array", "minItems": 1, "items": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "carrier ID" }, "description": "Array of Carrier IDs" } } }, "estimate_rates_by_carrier_id": { "title": "estimate_rates_by_carrier_id", "description": "A rate estimate request for a single carrier. Cannot be combined with `carrier_ids`.\n", "allOf": [ { "$ref": "#/components/schemas/rate_estimate_options" }, { "$ref": "#/components/schemas/rate_estimate_by_carrier_id" } ] }, "estimate_rates_by_carrier_ids": { "title": "estimate_rates_by_carrier_ids", "description": "A rate estimate request for one or more carriers. Cannot be combined with `carrier_id`.\n", "allOf": [ { "$ref": "#/components/schemas/rate_estimate_options" }, { "$ref": "#/components/schemas/rate_estimate_by_carrier_ids" } ] }, "estimate_rates_request_body": { "title": "estimate_rates_request_body", "description": "A rate estimate request body. Provide either `carrier_ids` or the deprecated\n`carrier_id`, but not both.\n", "oneOf": [ { "$ref": "#/components/schemas/estimate_rates_by_carrier_ids" }, { "$ref": "#/components/schemas/estimate_rates_by_carrier_id" } ] }, "rate_request_by_shipment_id": { "title": "rate_request_by_shipment_id", "type": "object", "description": "Identifies an existing shipment to rate", "additionalProperties": false, "required": [ "shipment_id" ], "properties": { "shipment_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "A string that uniquely identifies the shipment" } } }, "rate_request_by_shipment": { "title": "rate_request_by_shipment", "type": "object", "description": "The shipment to rate", "additionalProperties": false, "required": [ "shipment" ], "properties": { "shipment": { "allOf": [ { "$ref": "#/components/schemas/address_validating_shipment" } ], "description": "The shipment object" } } }, "calculate_rates_by_shipment_id": { "title": "calculate_rates_by_shipment_id", "description": "A rate request for an existing shipment. Cannot be combined with `shipment`.\n", "required": [ "rate_options" ], "allOf": [ { "$ref": "#/components/schemas/rate_request_rate_options" }, { "$ref": "#/components/schemas/rate_request_by_shipment_id" } ] }, "calculate_rates_by_shipment": { "title": "calculate_rates_by_shipment", "description": "A rate request for an inline shipment. Cannot be combined with `shipment_id`.\n", "required": [ "rate_options" ], "allOf": [ { "$ref": "#/components/schemas/rate_request_rate_options" }, { "$ref": "#/components/schemas/rate_request_by_shipment" } ] }, "calculate_rates_request_body": { "title": "calculate_rates_request_body", "description": "A rate shipment request body. Provide either `shipment_id` or `shipment`, but not both.\n", "oneOf": [ { "$ref": "#/components/schemas/calculate_rates_by_shipment_id" }, { "$ref": "#/components/schemas/calculate_rates_by_shipment" } ] }, "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": { "oneOf": [ { "$ref": "#/components/schemas/image_id" }, { "type": "null" } ], "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": { "$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": { "$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": { "$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": { "$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" } ], "properties": { "custom_field1": { "type": "string", "description": "Optional - Value will be saved in the shipment's advanced_options > custom_field1", "example": "Custom field 1" }, "custom_field2": { "type": "string", "description": "Optional - Value will be saved in the shipment's advanced_options > custom_field2", "example": "Custom field 2" }, "custom_field3": { "type": "string", "description": "Optional - Value will be saved in the shipment's advanced_options > custom_field3", "example": "Custom field 3" }, "external_shipment_id": { "type": [ "string", "null" ], "maxLength": 100, "description": "Optional - A unique user-defined key to identify a shipment limited to 100 characters.", "example": "my-shipment-001" } } }, "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": { "type": [ "string", "null" ], "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": { "type": [ "string", "null" ], "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_netstamps_labels_request_body": { "title": "create_netstamps_labels_request_body", "type": "object", "description": "Request body for creating NetStamps labels.", "required": [ "shipments", "label_layout" ], "additionalProperties": false, "properties": { "shipments": { "type": "array", "minItems": 1, "description": "The shipments to create NetStamps labels for. All shipments must use the same `carrier_id`.\n\nEach shipment must include `advanced_options.netstamps_options` with `row` and `column` to control stamp placement. Row/column combinations must be unique across shipments.\n", "items": { "$ref": "#/components/schemas/shipment" } }, "label_layout": { "type": "string", "description": "The NetStamps layout to use.\n", "example": "netstamps_traditional", "enum": [ "netstamps_traditional", "netstamps_standard", "netstamps_alternate", "netstamps_promotional", "netstamps_themed", "netstamps_photo_landscape", "netstamps_photo_portrait", "netstamps_photo_landscape_hs", "netstamps_return_address", "netstamps_roll_type_sd", "netstamps_promo_paper20" ] }, "label_format": { "type": "string", "default": "pdf", "example": "pdf", "enum": [ "pdf", "png" ], "description": "The file format for the label." }, "display_scheme": { "default": "label", "allOf": [ { "$ref": "#/components/schemas/display_scheme" } ], "description": "The display format that the label should be shown in." }, "test_label": { "type": "boolean", "default": false, "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." }, "label_download_type": { "default": "url", "allOf": [ { "$ref": "#/components/schemas/label_download_type" } ] }, "is_return_label": { "type": "boolean", "default": false, "example": true, "description": "Indicates whether these are return labels." }, "rma_number": { "type": [ "string", "null" ], "example": "asd12323", "description": "An optional Return Merchandise Authorization number for return labels." }, "charge_event": { "allOf": [ { "$ref": "#/components/schemas/label_charge_event" } ], "description": "The label charge event." }, "outbound_label_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The `label_id` of the original (outgoing) label that the return label is for." }, "validate_address": { "default": "no_validation", "allOf": [ { "$ref": "#/components/schemas/validate_address" } ] }, "label_image_id": { "oneOf": [ { "$ref": "#/components/schemas/image_id" }, { "type": "null" } ], "description": "The label image resource that was used to create a custom label image." }, "ship_to_service_point_id": { "type": [ "string", "null" ], "description": "A unique identifier for a carrier service point where the shipment will be delivered.", "example": "614940" }, "ship_from_service_point_id": { "type": [ "string", "null" ], "description": "A unique identifier for a carrier drop off point where a merchant plans to deliver packages.", "example": "614940" } } }, "create_mail_labels_request_body": { "title": "create_mail_labels_request_body", "type": "object", "description": "Request body for creating mail labels on a label sheet.", "required": [ "shipments", "label_layout", "mailing_options" ], "additionalProperties": false, "properties": { "shipments": { "type": "array", "minItems": 1, "description": "The shipments to create mail labels for. All shipments must use the same `carrier_id`.\n", "items": { "$ref": "#/components/schemas/shipment" } }, "mailing_options": { "type": "object", "description": "Layout options for printing mail labels on a single sheet. Controls the starting position on the label sheet.", "properties": { "start_row": { "type": "integer", "format": "int32", "minimum": 0, "default": 0, "example": 0, "description": "The row on the sheet where label placement begins." }, "start_column": { "type": "integer", "format": "int32", "minimum": 0, "default": 0, "example": 0, "description": "The column on the sheet where label placement begins." } } }, "label_layout": { "type": "string", "description": "The mail label layout to use.\n", "example": "mail_label_sdc3110", "enum": [ "mail_label_sdc3110", "mail_label_avery5160", "mail_label_avery5163" ] }, "label_format": { "type": "string", "default": "pdf", "example": "pdf", "enum": [ "pdf", "png" ], "description": "The file format for the label." }, "display_scheme": { "default": "label", "allOf": [ { "$ref": "#/components/schemas/display_scheme" } ], "description": "The display format that the label should be shown in." }, "test_label": { "type": "boolean", "default": false, "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." }, "label_download_type": { "default": "url", "allOf": [ { "$ref": "#/components/schemas/label_download_type" } ] }, "is_return_label": { "type": "boolean", "default": false, "example": true, "description": "Indicates whether these are return labels." }, "rma_number": { "type": [ "string", "null" ], "example": "asd12323", "description": "An optional Return Merchandise Authorization number for return labels." }, "charge_event": { "allOf": [ { "$ref": "#/components/schemas/label_charge_event" } ], "description": "The label charge event." }, "outbound_label_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The `label_id` of the original (outgoing) label that the return label is for." }, "validate_address": { "default": "no_validation", "allOf": [ { "$ref": "#/components/schemas/validate_address" } ] }, "label_image_id": { "oneOf": [ { "$ref": "#/components/schemas/image_id" }, { "type": "null" } ], "description": "The label image resource that was used to create a custom label image." }, "ship_to_service_point_id": { "type": [ "string", "null" ], "description": "A unique identifier for a carrier service point where the shipment will be delivered.", "example": "614940" }, "ship_from_service_point_id": { "type": [ "string", "null" ], "description": "A unique identifier for a carrier drop off point where a merchant plans to deliver packages.", "example": "614940" } } }, "create_envelope_label_request_body": { "title": "create_envelope_label_request_body", "type": "object", "description": "Request body for creating an envelope label.", "required": [ "shipment", "label_layout" ], "additionalProperties": false, "properties": { "shipment": { "allOf": [ { "$ref": "#/components/schemas/shipment" } ], "description": "The shipment information used to generate the envelope label." }, "label_layout": { "type": "string", "description": "The envelope layout to use.\n", "example": "envelope_9", "enum": [ "envelope_9", "envelope_10", "envelope_11", "envelope_12", "envelope_personal", "envelope_monarch", "envelope_greeting", "envelope_invitation", "envelope_traditional_single", "envelope_standard_single", "envelope_themed_single", "envelope_photo_landscape_single", "envelope_photo_portrait_single", "envelope_return_address_single", "envelope_alternate_single", "envelope_themed_alt_single" ] }, "label_format": { "type": "string", "default": "pdf", "example": "pdf", "enum": [ "pdf", "png", "zpl" ], "description": "The file format for the label." }, "display_scheme": { "default": "label", "allOf": [ { "$ref": "#/components/schemas/display_scheme" } ], "description": "The display format that the label should be shown in." }, "test_label": { "type": "boolean", "default": false, "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." }, "label_download_type": { "default": "url", "allOf": [ { "$ref": "#/components/schemas/label_download_type" } ] }, "is_return_label": { "type": "boolean", "default": false, "example": true, "description": "Indicates whether this is a return label." }, "rma_number": { "type": [ "string", "null" ], "example": "asd12323", "description": "An optional Return Merchandise Authorization number for return labels." }, "charge_event": { "allOf": [ { "$ref": "#/components/schemas/label_charge_event" } ], "description": "The label charge event." }, "outbound_label_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The `label_id` of the original (outgoing) label that the return label is for." }, "validate_address": { "default": "no_validation", "allOf": [ { "$ref": "#/components/schemas/validate_address" } ] }, "label_image_id": { "oneOf": [ { "$ref": "#/components/schemas/image_id" }, { "type": "null" } ], "description": "The label image resource that was used to create a custom label image." }, "ship_to_service_point_id": { "type": [ "string", "null" ], "description": "A unique identifier for a carrier service point where the shipment will be delivered.", "example": "614940" }, "ship_from_service_point_id": { "type": [ "string", "null" ], "description": "A unique identifier for a carrier drop off point where a merchant plans to deliver packages.", "example": "614940" } } }, "multi_label_response_body": { "title": "multi_label_response_body", "type": "object", "description": "Response containing multiple labels created from a mailing request.\nExtends the standard label with a total cost summary and associated labels.\n", "additionalProperties": false, "allOf": [ { "$ref": "#/components/schemas/label" }, { "type": "object", "properties": { "total_cost": { "allOf": [ { "$ref": "#/components/schemas/monetary_value" } ], "readOnly": true, "description": "The combined cost of all labels in this mailing request." }, "associated_labels": { "type": "array", "readOnly": true, "description": "The individual labels created for each shipment in the request.", "items": { "$ref": "#/components/schemas/create_label_response_body" } } } } ] }, "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" } } }, "create_label_from_shipping_rule_request_body": { "title": "create_label_from_shipping_rule_request_body", "type": "object", "description": "Request body for creating a label using a Shipping Rule. The Shipping Rule automatically selects the carrier and service based on its configuration.\n\n**Important Constraints:**\n- You MUST NOT include `carrier_id`, `service_code`, or `shipping_rule_id` in the shipment (the Shipping Rule selects these automatically)\n", "required": [ "shipment" ], "additionalProperties": false, "properties": { "shipment": { "allOf": [ { "$ref": "#/components/schemas/partial_shipment_for_shipping_rule" } ], "description": "Shipment details. Must NOT include carrier_id, service_code, or\nshipping_rule_id as the Shipping Rule 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" } } }, "partial_shipment_for_shipping_rule": { "title": "partial_shipment_for_shipping_rule", "type": "object", "description": "Shipment information for Shipping Rule. Must NOT include carrier_id, service_code,\nor shipping_rule_id as the Shipping Rule selects these automatically.\n", "additionalProperties": false, "properties": { "requested_shipment_service": { "type": [ "string", "null" ], "description": "The requested shipment service", "example": "usps_priority_mail" }, "external_order_id": { "type": [ "string", "null" ], "example": "1232434", "description": "ID that the Order Source assigned" }, "hold_until_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date to hold the shipment until", "example": "2025-01-15T00:00:00.000Z" }, "ship_by_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date by which the shipment should be shipped", "example": "2025-01-15T00:00:00.000Z" }, "deliver_by_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date by which the shipment should be delivered", "example": "2025-01-20T00:00:00.000Z" }, "retail_rate": { "oneOf": [ { "$ref": "#/components/schemas/monetary_value" }, { "type": "null" } ], "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": { "$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", "null" ], "description": "Notes from the buyer", "example": "Please handle with care" }, "notes_to_buyer": { "type": [ "string", "null" ], "description": "Notes to the buyer", "example": "Thank you for your order!" }, "notes_for_gift": { "type": [ "string", "null" ], "description": "Gift notes", "example": "Happy Birthday!" }, "internal_notes": { "type": [ "string", "null" ], "description": "Internal notes from the seller", "example": "Check packaging before shipping" }, "is_gift": { "type": "boolean", "default": false, "description": "Indicates if the shipment is a gift", "example": true }, "assigned_user": { "type": [ "string", "null" ], "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", "null" ], "format": "int32", "minimum": 0, "description": "Shipping zone", "example": 1 }, "display_scheme": { "type": [ "string", "null" ], "description": "Display scheme for the shipment", "example": "label" }, "tax_identifiers": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/tax_identifier" } }, "external_shipment_id": { "type": [ "string", "null" ], "maxLength": 50, "example": "1234556", "description": "A user-defined key that identifies the source order. Multiple shipments can share the same `external_shipment_id` (common in split-shipping scenarios where one order results in multiple shipments). Functionally identical to `orderKey` in V1 API.\n\n> **Warning:** The `external_shipment_id` is limited to 50 characters. Any additional characters will be truncated.\n" }, "shipment_number": { "type": [ "string", "null" ], "maxLength": 50, "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": { "oneOf": [ { "$ref": "#/components/schemas/date" }, { "type": "null" } ], "description": "The date that the shipment was (or will be) shipped. 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" }, "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": { "default": null, "oneOf": [ { "$ref": "#/components/schemas/se_id" }, { "type": "null" } ], "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", "null" ], "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 for this shipment. Defaults to 'none' if not specified." }, "customs": { "oneOf": [ { "$ref": "#/components/schemas/international_shipment_options" }, { "type": "null" } ], "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": { "$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": { "$ref": "#/components/schemas/order_source_name" }, "packages": { "type": "array", "minItems": 1, "items": { "$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" }, "comparison_rate_type": { "type": [ "string", "null" ], "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" } } }, "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." }, "generate_packing_slips": { "type": "boolean", "default": false, "example": true, "description": "When `true`, a packing slip is generated for each shipment in the batch and placed in line with the\nlabels in the `label_download` file. A separate download link for all packing slips in the batch is\nreturned in `packing_slip_download`.\n" } } }, "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 ID" }, "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": { "$ref": "#/components/schemas/currency" }, "is_return": { "type": "boolean", "description": "Indicate if it's a return shipment", "example": true }, "rate_type": { "allOf": [ { "$ref": "#/components/schemas/rate_type" } ], "description": "Indicates what type of rating to perform", "example": "shipment" } } }, "rate_request_rate_options": { "title": "rate_request_rate_options", "type": "object", "additionalProperties": false, "properties": { "rate_options": { "allOf": [ { "$ref": "#/components/schemas/rate_request_body" } ], "description": "The rate options" } } }, "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": { "$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", "null" ], "maxLength": 50, "example": "1751939189", "description": "A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.\n" }, "carrier_id": { "oneOf": [ { "$ref": "#/components/schemas/se_id" }, { "type": "null" } ], "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": { "type": [ "string", "null" ], "description": "The store ID associated with the shipment", "example": "1582173" }, "notes_from_buyer": { "type": [ "string", "null" ], "description": "Notes from the buyer", "example": "I am a note from the buyer" }, "notes_to_buyer": { "type": [ "string", "null" ], "description": "Notes to the buyer", "example": "Thank you for your order!" }, "notes_for_gift": { "type": [ "string", "null" ], "description": "Gift notes", "example": "I am a gift note" }, "internal_notes": { "type": [ "string", "null" ], "description": "Internal notes from the seller", "example": "Check packaging before shipping" }, "is_gift": { "type": "boolean", "default": false, "description": "Indicates if the shipment is a gift", "example": true }, "zone": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0, "description": "Shipping zone", "example": 0 }, "display_scheme": { "type": [ "string", "null" ], "description": "Display scheme for the shipment", "example": "paperless" }, "requested_shipment_service": { "type": [ "string", "null" ], "description": "The requested shipment service", "example": "usps_priority_mail" }, "deliver_by_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date by which the shipment should be delivered", "example": "2025-01-20T00:00:00.000Z" }, "assigned_user": { "type": [ "string", "null" ], "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" }, "warehouse_id": { "oneOf": [ { "$ref": "#/components/schemas/se_id" }, { "type": "null" } ], "description": "The warehouse ID to use as the ship from location. This is an alternative to providing a ship_from address object.\nYou cannot specify both warehouse_id and ship_from in the same request.\n", "example": "se-2774150" }, "items": { "type": "array", "default": [], "items": { "$ref": "#/components/schemas/shipment_item" }, "description": "Items included in this shipment" }, "packages": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/package" }, "description": "The packages in the shipment" } } }, "assign_user_request_body": { "title": "assign_user_request_body", "type": "object", "description": "A request body for assigning a user to shipments", "required": [ "shipment_ids", "user_id" ], "additionalProperties": false, "properties": { "shipment_ids": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/se_id" }, "description": "Array of shipment IDs to assign the user to", "example": [ "se-202902255", "se-202902256" ] }, "user_id": { "type": "string", "format": "uuid", "description": "The ID of the user to assign to the shipments", "example": "a2df9fa5-b7ee-467f-be4e-9c660542c187" } } }, "hold_shipment_request_body": { "title": "hold_shipment_request_body", "type": "object", "description": "A request body for holding a shipment", "required": [ "hold_until_date" ], "additionalProperties": false, "properties": { "hold_until_date": { "type": "string", "format": "date", "description": "The date to hold the shipment until. This is a date-only value — you can send a\nplain `YYYY-MM-DD` date, and any time component is ignored. The date must be\nlater than today.\n", "example": "2026-10-15" } } }, "hold_shipment_response_body": { "title": "hold_shipment_response_body", "type": "object", "description": "A response body for holding a shipment", "additionalProperties": false, "properties": { "shipment_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The ID of the shipment that was put on hold", "example": "se-202902255" }, "hold_until_date": { "type": "string", "format": "date-time", "description": "The date the shipment is held until, returned at midnight", "example": "2026-10-15T00:00:00Z" } } }, "restore_shipment_response_body": { "title": "restore_shipment_response_body", "type": "object", "description": "A response body for restoring a shipment that is on hold", "additionalProperties": false, "properties": { "shipment_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The ID of the shipment that was restored", "example": "se-202902255" } } }, "hold_shipments_request_body": { "title": "hold_shipments_request_body", "type": "object", "description": "A request body for holding one or more shipments", "required": [ "shipment_ids", "hold_until_date" ], "additionalProperties": false, "properties": { "shipment_ids": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/se_id" }, "description": "Array of shipment IDs to hold", "example": [ "se-202902255", "se-202902256" ] }, "hold_until_date": { "type": "string", "format": "date", "description": "The date to hold the shipments until. This is a date-only value — you can send a\nplain `YYYY-MM-DD` date, and any time component is ignored. The date must be\nlater than today.\n", "example": "2026-10-15" } } }, "hold_shipments_response_body": { "title": "hold_shipments_response_body", "type": "object", "description": "A response body for holding one or more shipments", "additionalProperties": false, "properties": { "shipment_ids": { "type": "array", "items": { "$ref": "#/components/schemas/se_id" }, "description": "Array of shipment IDs that were put on hold", "example": [ "se-202902255", "se-202902256" ] }, "hold_until_date": { "type": "string", "format": "date-time", "description": "The date the shipments are held until, returned at midnight. Absent when no shipment was held.", "example": "2026-10-15T00:00:00Z" }, "errors": { "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/error" }, "description": "The shipments that could not be held, with the reason for each. Empty when every shipment was processed." }, "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" } } }, "restore_shipments_request_body": { "title": "restore_shipments_request_body", "type": "object", "description": "A request body for restoring one or more shipments that are on hold", "required": [ "shipment_ids" ], "additionalProperties": false, "properties": { "shipment_ids": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/se_id" }, "description": "Array of shipment IDs to restore", "example": [ "se-202902255", "se-202902256" ] } } }, "restore_shipments_response_body": { "title": "restore_shipments_response_body", "type": "object", "description": "A response body for restoring one or more shipments that are on hold", "additionalProperties": false, "properties": { "shipment_ids": { "type": "array", "items": { "$ref": "#/components/schemas/se_id" }, "description": "Array of shipment IDs that were restored", "example": [ "se-202902255", "se-202902256" ] }, "errors": { "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/error" }, "description": "The shipments that could not be restored, with the reason for each. Empty when every shipment was processed." }, "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" } } }, "assign_user_to_batch_request_body": { "title": "assign_user_to_batch_request_body", "type": "object", "description": "A request body for assigning a user to a batch", "required": [ "assigned_user" ], "additionalProperties": false, "properties": { "assigned_user": { "type": "string", "format": "uuid", "description": "The ID of the user to assign to the batch. The user must be an active member of your account.", "example": "a2df9fa5-b7ee-467f-be4e-9c660542c187" } } }, "split_shipment_request_body": { "title": "split_shipment_request_body", "type": "object", "description": "A request body for splitting a shipment into one or more new shipments", "required": [ "shipments" ], "additionalProperties": false, "properties": { "shipments": { "type": "array", "minItems": 1, "maxItems": 100, "description": "The new shipments to create. Each entry creates one new shipment that holds the listed items.\nItems and quantities that you don't list stay on the original shipment.\n", "items": { "type": "object", "title": "split_shipment_new_shipment", "description": "A new shipment to create from the original shipment", "required": [ "items" ], "additionalProperties": false, "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 200, "description": "The items to move from the original shipment into this new shipment", "items": { "type": "object", "title": "split_shipment_item", "description": "An item to move, and how many units of it to move", "required": [ "item_id", "quantity" ], "additionalProperties": false, "properties": { "item_id": { "type": "string", "minLength": 1, "description": "The `item_id` of an item on the original shipment, from the `items` array returned by\n[Get shipment by id](#operation/get_shipment_by_id). Each item can be listed only once\nin the same new shipment.\n", "example": "1402291169813" }, "quantity": { "type": "integer", "format": "int32", "minimum": 1, "description": "The number of units of the item to move into the new shipment. Across all new\nshipments, the total for an item can't be more than the quantity on the original shipment.\n", "example": 1 } } } } } } } } }, "split_shipment_response_body": { "title": "split_shipment_response_body", "type": "object", "description": "A response body for splitting a shipment", "additionalProperties": false, "properties": { "shipment_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The original shipment, which keeps the items that weren't moved", "example": "se-202902255" }, "new_shipment_ids": { "type": "array", "items": { "$ref": "#/components/schemas/se_id" }, "description": "The new shipments, in the same order as the `shipments` array in the request", "example": [ "se-202902301" ] } } }, "merge_shipments_request_body": { "title": "merge_shipments_request_body", "type": "object", "description": "A request body for merging shipments into a shipment", "required": [ "shipment_ids" ], "additionalProperties": false, "properties": { "shipment_ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/se_id" }, "description": "The shipments to merge into the shipment in the URL. At least one of them must be a shipment other\nthan the one in the URL.\n", "example": [ "se-202902301", "se-202902302" ] } } }, "merge_shipments_response_body": { "title": "merge_shipments_response_body", "type": "object", "description": "A response body for merging shipments", "additionalProperties": false, "properties": { "shipment_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The shipment that now holds all of the items", "example": "se-202902255" }, "merged_shipment_ids": { "type": "array", "items": { "$ref": "#/components/schemas/se_id" }, "description": "The shipments that were merged in. These shipments have been deleted.", "example": [ "se-202902301", "se-202902302" ] } } }, "assign_user_response_body": { "title": "assign_user_response_body", "type": "object", "description": "A response body for assigning a user to shipments", "additionalProperties": false, "properties": { "shipment_ids": { "type": "array", "items": { "$ref": "#/components/schemas/se_id" }, "description": "Array of shipment IDs that were assigned to the user", "example": [ "se-202902255", "se-202902256" ] }, "user_id": { "type": "string", "format": "uuid", "description": "The ID of the user assigned to the shipments", "example": "a2df9fa5-b7ee-467f-be4e-9c660542c187" } } }, "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": { "$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": { "oneOf": [ { "$ref": "#/components/schemas/address_validation_result" }, { "type": "null" } ], "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" }, "assigned_user": { "type": "string", "format": "uuid", "example": "a2df9fa5-b7ee-467f-be4e-9c660542c187", "description": "Assign a user to the batch at creation time. The user must be an active member of your account." }, "shipment_ids": { "type": "array", "items": { "$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." }, "generate_packing_slips": { "type": "boolean", "default": false, "example": true, "description": "When `true`, a packing slip is generated for each shipment in the batch and placed in line with the\nlabels in the `label_download` file. A separate download link for all packing slips in the batch is\nreturned in `packing_slip_download`.\n" } } } } }, "validate_address_request_body": { "type": "array", "description": "An address validation request body", "items": { "type": "object", "description": "Any residential or business mailing address, anywhere in the world", "required": [ "address_line1", "city_locality", "state_province", "country_code" ], "properties": { "name": { "type": "string", "minLength": 1, "example": "John Doe", "description": "The name of a contact person at this address" }, "phone": { "type": "string", "minLength": 1, "example": "+1 204-253-9411 ext. 123", "description": "The phone number of a contact person at this address" }, "company_name": { "type": [ "string", "null" ], "minLength": 1, "example": "The Home Depot", "description": "If this is a business address, then the company name should be specified here" }, "address_line1": { "type": "string", "minLength": 1, "example": "1999 Bishop Grandin Blvd.", "description": "The first line of the street address" }, "address_line2": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "example": "Unit 408", "description": "The second line of the street address" }, "address_line3": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "example": "Building #7", "description": "The third line of the street address" }, "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" }, "postal_code": { "type": "string", "minLength": 1, "example": "78756", "description": "postal code" }, "country_code": { "type": "string", "minLength": 2, "maxLength": 2, "example": "CA", "description": "The two-letter ISO 3166-1 country code" }, "address_residential_indicator": { "type": "string", "example": "no", "description": "Indicates whether this is a residential address" } } } }, "validate_address_response_body": { "type": "array", "description": "An address validation response body", "items": { "type": "object", "description": "An address validation result", "required": [ "status", "original_address", "matched_address", "messages" ], "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "unverified", "verified", "warning", "error" ], "description": "The address validation status", "example": "verified" }, "original_address": { "type": "object", "description": "The original address that was sent for validation", "properties": { "name": { "type": "string", "example": "Mickey and Minnie Mouse" }, "phone": { "type": "string", "example": "714-781-4565" }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "example": "The Walt Disney Company" }, "address_line1": { "type": "string", "example": "500 South Buena Vista Street" }, "address_line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "example": null }, "address_line3": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "example": null }, "city_locality": { "type": "string", "example": "Burbank" }, "state_province": { "type": "string", "example": "CA" }, "postal_code": { "type": "string", "example": "91521" }, "country_code": { "type": "string", "example": "US" }, "address_residential_indicator": { "type": "string", "example": "unknown" } } }, "matched_address": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "readOnly": true, "description": "The matched address found by the ShipStation API API", "properties": { "name": { "type": "string", "example": "MICKEY AND MINNIE MOUSE" }, "phone": { "type": "string", "example": "714-781-4565" }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "example": "THE WALT DISNEY COMPANY" }, "address_line1": { "type": "string", "example": "500 S BUENA VISTA ST" }, "address_line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "example": null }, "address_line3": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "example": null }, "city_locality": { "type": "string", "example": "BURBANK" }, "state_province": { "type": "string", "example": "CA" }, "postal_code": { "type": "string", "example": "91521-0007" }, "country_code": { "type": "string", "example": "US" }, "address_residential_indicator": { "type": "string", "example": "no" } } }, "messages": { "type": "array", "readOnly": true, "default": [], "description": "The list of messages that were generated during the address validation request", "items": { "type": "object", "description": "A response message", "additionalProperties": false, "required": [ "code", "message", "type", "detail_code" ], "properties": { "code": { "type": "string", "readOnly": true, "example": "a1004", "description": "The message code" }, "message": { "type": "string", "readOnly": true, "example": "Address verified successfully", "description": "The message text" }, "type": { "type": "string", "enum": [ "info", "warning", "error" ], "readOnly": true, "example": "info", "description": "The message type" }, "detail_code": { "type": "string", "readOnly": true, "example": "address_verified", "description": "The detailed message code" } } } } } } }, "manufacturer_product_identifier_type": { "title": "manufacturer_product_identifier_type", "type": "string", "enum": [ "undefined", "gtin", "ean", "isbn", "upc", "mpn", "sku" ], "description": "The type of manufacturer product identifier. GTIN (Global Trade Item Number), EAN (European Article Number), ISBN (International Standard Book Number), UPC (Universal Product Code), MPN (Manufacturer Part Number), SKU (Stock Keeping Unit). Use `undefined` when the specific identifier type is not defined in this list." }, "cpsc_certificate": { "title": "cpsc_certificate", "type": "object", "description": "A US Consumer Product Safety Commission (CPSC) eFiling certificate associated with a product in the shipment.", "additionalProperties": false, "properties": { "certifier_id": { "type": "string", "maxLength": 50, "description": "Unique identifier assigned to the certifier by the CPSC.", "example": "CERT-12345" }, "certificate_version_id": { "type": "string", "maxLength": 50, "description": "The version identifier of the CPSC certificate.", "example": "v1.0" } } }, "checkout_rates_service_selection": { "title": "checkout_rates_service_selection", "type": "object", "description": "A carrier and service pairing used by `live_rate` and `local_delivery` delivery options. Both fields are required for each entry.\n", "additionalProperties": false, "required": [ "carrier_id", "service_code" ], "properties": { "carrier_id": { "type": "string", "pattern": "^se-[0-9]+$", "example": "se-1234567", "description": "The ID of a carrier connected to your account, in the format `se-` followed by digits (for example, `se-1234567`). A value that does not match this format is rejected with a validation error, and a well-formed ID that is not connected to your account is rejected as an invalid identifier.\n" }, "service_code": { "type": "string", "minLength": 1, "example": "usps_priority_mail", "description": "The service code of the carrier service to rate (for example, `usps_priority_mail`). Required for each service; a service code that is not available for the carrier is rejected as an invalid identifier.\n" } } }, "checkout_rates_dimensions_by_weight": { "title": "checkout_rates_dimensions_by_weight", "type": "object", "description": "A default package size to apply to carts whose total weight is at or below `max_weight`. Used when the configuration calculates live rates without explicit package dimensions.\n", "additionalProperties": false, "properties": { "max_weight": { "allOf": [ { "$ref": "#/components/schemas/weight" } ], "description": "The upper weight bound this default package applies to." }, "default_dimensions": { "allOf": [ { "$ref": "#/components/schemas/dimensions" } ], "description": "The default package dimensions to use for carts within this weight bound." } } }, "checkout_rates_shared_settings": { "title": "checkout_rates_shared_settings", "type": "object", "description": "Settings shared by every delivery option in a configuration, controlling how live rates are calculated.\n", "additionalProperties": false, "properties": { "calculation_method": { "type": "string", "enum": [ "by_volume", "skip_dimensions" ], "example": "by_volume", "description": "How package dimensions are determined when calculating live rates. `by_volume` derives a package size from the cart; `skip_dimensions` rates without dimensions.\n" }, "dimensions_by_weight": { "type": "array", "items": { "$ref": "#/components/schemas/checkout_rates_dimensions_by_weight" }, "description": "Default package dimensions applied to carts by weight bound." } } }, "checkout_rates_option_request_body": { "title": "checkout_rates_option_request_body", "type": "object", "description": "The configuration of a single delivery option. The fields that apply depend on `type`:\n\n- `live_rate` and `local_delivery` use `services` (and may apply `fee_mode`/`fee_percentage`); `live_rate` may also define a `fallback_mode`.\n- `flat_rate` uses `amount`/`currency`.\n- `free` requires no additional fields.\n", "additionalProperties": false, "required": [ "name", "type" ], "properties": { "name": { "type": "string", "minLength": 1, "example": "Standard Shipping", "description": "The display name of the delivery option. Must be unique within the configuration." }, "type": { "type": "string", "enum": [ "live_rate", "flat_rate", "free", "local_delivery" ], "example": "live_rate", "description": "The kind of delivery option." }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/checkout_rates_service_selection" }, "description": "The carrier/service pairings to rate. Applies to `live_rate` and `local_delivery` options." }, "fee_mode": { "type": "string", "enum": [ "add", "subtract" ], "example": "add", "description": "Whether the fee defined by `fee_percentage` is added to or subtracted from the carrier rate. Omit for a pass-through rate.\n" }, "fee_percentage": { "type": "number", "example": 10, "description": "The percentage of the carrier rate to add or subtract, according to `fee_mode`." }, "sort_index": { "type": "integer", "example": 0, "description": "The position of this option relative to the others in the configuration, ascending." }, "fallback_mode": { "type": "string", "enum": [ "dont_show", "flat_rate", "cart_percentage" ], "example": "flat_rate", "description": "What to show when live rates cannot be retrieved. `dont_show` hides the option; `flat_rate` shows `fallback_rate_amount`/`fallback_rate_currency`; `cart_percentage` shows `fallback_percentage` of the cart total.\n" }, "fallback_rate_amount": { "type": "number", "example": 5, "description": "The fixed fallback price, when `fallback_mode` is `flat_rate`." }, "fallback_rate_currency": { "type": "string", "example": "USD", "description": "The currency of `fallback_rate_amount`." }, "fallback_percentage": { "type": "number", "example": 5, "description": "The percentage of the cart total to charge, when `fallback_mode` is `cart_percentage`." }, "amount": { "type": "number", "example": 4.99, "description": "The fixed price for a `flat_rate` option." }, "currency": { "type": "string", "example": "USD", "description": "The currency of `amount`." } } }, "checkout_rates_option_response_body": { "title": "checkout_rates_option_response_body", "type": "object", "description": "A delivery option belonging to a checkout rates configuration.", "additionalProperties": false, "properties": { "option_id": { "type": "integer", "readOnly": true, "example": 100001, "description": "The unique identifier of the delivery option." }, "config_id": { "type": "string", "readOnly": true, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "description": "The identifier of the configuration this option belongs to." }, "name": { "type": "string", "example": "Standard Shipping", "description": "The display name of the delivery option." }, "type": { "type": "string", "enum": [ "live_rate", "flat_rate", "free", "local_delivery" ], "example": "live_rate", "description": "The kind of delivery option." }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/checkout_rates_service_selection" }, "description": "The carrier/service pairings rated by this option, when applicable." }, "fee_mode": { "type": "string", "enum": [ "add", "subtract" ], "example": "add", "description": "Whether `fee_percentage` is added to or subtracted from the carrier rate." }, "fee_percentage": { "type": "number", "example": 10, "description": "The percentage of the carrier rate added or subtracted, according to `fee_mode`." }, "sort_index": { "type": "integer", "example": 0, "description": "The position of this option relative to the others in the configuration, ascending." }, "fallback_mode": { "type": "string", "enum": [ "dont_show", "flat_rate", "cart_percentage" ], "example": "flat_rate", "description": "What is shown when live rates cannot be retrieved." }, "fallback_rate_amount": { "type": "number", "example": 5, "description": "The fixed fallback price, when `fallback_mode` is `flat_rate`." }, "fallback_rate_currency": { "type": "string", "example": "USD", "description": "The currency of `fallback_rate_amount`." }, "fallback_percentage": { "type": "number", "example": 5, "description": "The percentage of the cart total charged, when `fallback_mode` is `cart_percentage`." }, "amount": { "type": "number", "example": 0, "description": "The fixed price for a `flat_rate` option." }, "currency": { "type": "string", "example": "USD", "description": "The currency of `amount`." }, "is_active": { "type": "boolean", "readOnly": true, "example": true, "description": "Whether the option is active and shown at checkout." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "example": "2026-05-15T18:30:00Z", "description": "When the option was created." } } }, "create_checkout_rates_config_request_body": { "title": "create_checkout_rates_config_request_body", "type": "object", "description": "The configuration to create, including its initial delivery options and shared settings.", "additionalProperties": false, "properties": { "options": { "type": "array", "items": { "$ref": "#/components/schemas/checkout_rates_option_request_body" }, "description": "The delivery options to create with the configuration." }, "shared_settings": { "allOf": [ { "$ref": "#/components/schemas/checkout_rates_shared_settings" } ], "description": "Settings shared by every option in the configuration." } } }, "checkout_rates_config_response_body": { "title": "checkout_rates_config_response_body", "type": "object", "description": "A checkout rates configuration with its delivery options and shared settings.", "additionalProperties": false, "properties": { "config_id": { "type": "string", "readOnly": true, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "description": "The unique identifier of the configuration." }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/checkout_rates_option_response_body" }, "description": "The delivery options in the configuration." }, "shared_settings": { "allOf": [ { "$ref": "#/components/schemas/checkout_rates_shared_settings" } ], "description": "Settings shared by every option in the configuration." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "example": "2026-05-15T18:30:00Z", "description": "When the configuration was created." } } }, "checkout_rates_config_summary": { "title": "checkout_rates_config_summary", "type": "object", "description": "An identifying summary of a checkout rates configuration, as returned when listing configurations.", "additionalProperties": false, "properties": { "config_id": { "type": "string", "readOnly": true, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "description": "The unique identifier of the configuration." }, "is_active": { "type": "boolean", "readOnly": true, "example": true, "description": "Whether the configuration is active." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "example": "2026-05-15T18:30:00Z", "description": "When the configuration was created." } } }, "list_checkout_rates_configs_response_body": { "title": "list_checkout_rates_configs_response_body", "type": "array", "description": "The checkout rates configurations on the account.", "items": { "$ref": "#/components/schemas/checkout_rates_config_summary" } }, "checkout_rates_ship_to": { "title": "checkout_rates_ship_to", "type": "object", "description": "The destination address to calculate rates for.", "additionalProperties": false, "properties": { "address_type": { "type": "string", "example": "residential", "description": "The kind of address, when known (for example, `residential` or `commercial`)." }, "address_line1": { "type": "string", "example": "525 S Winchester Blvd", "description": "The first line of the street address." }, "address_line2": { "type": "string", "example": "Suite 200", "description": "The second line of the street address, when applicable." }, "address_line3": { "type": "string", "example": "Apt 12", "description": "The third line of the street address, when applicable." }, "city_locality": { "type": "string", "example": "San Jose", "description": "The city or locality." }, "state_province": { "type": "string", "example": "CA", "description": "The state or province." }, "postal_code": { "type": "string", "example": "95128", "description": "The postal code." }, "country_code": { "type": "string", "example": "US", "description": "The ISO 3166-1 alpha-2 country code." } } }, "checkout_rates_ship_from": { "title": "checkout_rates_ship_from", "type": "object", "description": "The origin address to calculate rates from. When this address is omitted, rates are calculated from the origin on the account's registration.\n\nThe origin applies to `live_rate` and `local_delivery` options. Pickup point options are unaffected.\n", "additionalProperties": false, "required": [ "postal_code", "country_code" ], "properties": { "address_type": { "type": "string", "example": "commercial", "description": "The kind of address, when known (for example, `residential` or `commercial`). Treated as unknown when omitted." }, "address_line1": { "type": "string", "example": "500 Warehouse Rd", "description": "The first line of the street address." }, "address_line2": { "type": "string", "example": "Dock 4", "description": "The second line of the street address, when applicable." }, "address_line3": { "type": "string", "example": "Bay 9", "description": "The third line of the street address, when applicable." }, "city_locality": { "type": "string", "example": "Austin", "description": "The city or locality." }, "state_province": { "type": "string", "example": "TX", "description": "The state or province." }, "postal_code": { "type": "string", "example": "78702", "description": "The postal code. Required when `ship_from` is supplied." }, "country_code": { "type": "string", "example": "US", "description": "The ISO 3166-1 alpha-2 country code. Required when `ship_from` is supplied." } } }, "checkout_rates_item": { "title": "checkout_rates_item", "type": "object", "description": "A line item in the cart being rated.", "additionalProperties": false, "properties": { "name": { "type": "string", "example": "T-Shirt", "description": "The name of the item." }, "quantity": { "type": "integer", "example": 2, "description": "The number of units of the item in the cart." }, "sku": { "type": "string", "example": "SKU-1234", "description": "The stock keeping unit (SKU) of the item." }, "price": { "type": "number", "example": 19.99, "description": "The unit price of the item." }, "weight": { "allOf": [ { "$ref": "#/components/schemas/weight" } ], "description": "The weight of a single unit of the item." }, "dimensions": { "allOf": [ { "$ref": "#/components/schemas/dimensions" } ], "description": "The dimensions of a single unit of the item." } } }, "calculate_checkout_rates_request_body": { "title": "calculate_checkout_rates_request_body", "type": "object", "description": "The destination and cart contents to calculate checkout rates for, and optionally the origin to calculate them from.", "additionalProperties": false, "required": [ "ship_to", "items" ], "properties": { "ship_from": { "allOf": [ { "$ref": "#/components/schemas/checkout_rates_ship_from" } ], "description": "The origin to calculate rates from. Optional; when omitted, the origin comes from the account's registration." }, "ship_to": { "allOf": [ { "$ref": "#/components/schemas/checkout_rates_ship_to" } ], "description": "The destination address." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/checkout_rates_item" }, "description": "The items in the cart." }, "currency": { "type": "string", "example": "USD", "description": "The currency to return rates in." } } }, "checkout_rates_rate_option": { "title": "checkout_rates_rate_option", "type": "object", "description": "A single rate returned for a delivery option. Each rate is an individually retrievable quote identified by its own `quote_id`.", "additionalProperties": false, "properties": { "quote_id": { "type": "string", "readOnly": true, "example": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "description": "The unique identifier of this rate's quote. Use it to retrieve the quote later with [Get a checkout rate quote](#operation/get_checkout_rates_quote)." }, "option_id": { "type": "integer", "readOnly": true, "example": 100001, "description": "The identifier of the delivery option this rate was produced for." }, "option_name": { "type": "string", "readOnly": true, "example": "Standard Shipping", "description": "The display name of the delivery option." }, "type": { "type": "string", "readOnly": true, "enum": [ "live_rate", "flat_rate", "free", "local_delivery" ], "example": "live_rate", "description": "The delivery option type this rate corresponds to (for example, `live_rate` or `free`)." }, "carrier_id": { "type": [ "string", "null" ], "readOnly": true, "example": "se-1234567", "description": "The carrier this rate is for. `null` for options without a carrier (for example, `free`)." }, "service_code": { "type": [ "string", "null" ], "readOnly": true, "example": "usps_priority_mail", "description": "The carrier service this rate is for. `null` for options without a carrier service." }, "final_amount": { "type": "number", "readOnly": true, "example": 10.69, "description": "The price shown to the buyer after fees or fallbacks are applied." }, "currency": { "type": "string", "readOnly": true, "example": "USD", "description": "The currency of `final_amount`." }, "estimated_delivery_days": { "type": [ "integer", "null" ], "readOnly": true, "example": 2, "description": "The carrier's estimated number of days in transit, when available." }, "estimated_delivery_date": { "type": [ "string", "null" ], "format": "date-time", "readOnly": true, "example": "2026-06-26T00:00:00Z", "description": "The carrier's estimated delivery date, when available." }, "delivery_prediction": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/delivery_prediction" } ], "description": "ShipStation's predicted delivery date for this rate.\n" } } }, "calculate_checkout_rates_response_body": { "title": "calculate_checkout_rates_response_body", "type": "object", "description": "The rates calculated for a cart. Each rate carries its own `quote_id`.", "additionalProperties": false, "properties": { "config_id": { "type": "string", "readOnly": true, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "description": "The configuration the rates were calculated against." }, "rates": { "type": "array", "items": { "$ref": "#/components/schemas/checkout_rates_rate_option" }, "description": "The rates to display at checkout, one entry per delivery option that produced a rate. Each entry has its own `quote_id`." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "example": "2026-06-24T10:00:00Z", "description": "When the quote was calculated." } } }, "checkout_rates_quote_response_body": { "title": "checkout_rates_quote_response_body", "type": "object", "description": "A previously calculated rate quote.", "additionalProperties": false, "properties": { "config_id": { "type": "string", "readOnly": true, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "description": "The configuration the rate was calculated against." }, "quote": { "allOf": [ { "$ref": "#/components/schemas/checkout_rates_rate_option" } ], "description": "The rate returned for this quote, including its `quote_id`." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "example": "2026-06-24T10:00:00Z", "description": "When the quote was calculated." } } }, "delivery_prediction_carrier_details": { "title": "delivery_prediction_carrier_details", "type": "object", "description": "The carrier and service a delivery prediction or warning belongs to.", "additionalProperties": false, "required": [ "carrier_code", "service_code" ], "properties": { "carrier_code": { "type": "string", "example": "ups", "description": "The carrier code, in lowercase." }, "service_code": { "type": "string", "example": "ups_ground", "description": "The carrier service code, in lowercase." } } }, "delivery_prediction_option": { "title": "delivery_prediction_option", "type": "object", "description": "A carrier and service combination to predict a delivery date for.", "additionalProperties": false, "required": [ "carrier_details" ], "properties": { "carrier_details": { "allOf": [ { "$ref": "#/components/schemas/delivery_prediction_carrier_details" } ], "description": "The carrier and service to predict for." } } }, "delivery_predictions_request_body": { "title": "delivery_predictions_request_body", "type": "object", "description": "The lane and the carrier and service combinations to predict delivery dates for.", "additionalProperties": false, "required": [ "from_country_code", "from_postal_code", "to_country_code", "to_postal_code", "delivery_options" ], "properties": { "from_country_code": { "type": "string", "example": "US", "description": "The ISO 3166-1 alpha-2 country code of the origin." }, "from_postal_code": { "type": "string", "example": "78701", "description": "The postal code of the origin." }, "to_country_code": { "type": "string", "example": "US", "description": "The ISO 3166-1 alpha-2 country code of the destination." }, "to_postal_code": { "type": "string", "example": "90210", "description": "The postal code of the destination." }, "ship_date": { "type": "string", "format": "date", "example": "2026-07-01", "description": "The date the shipment leaves the origin. Defaults to today when omitted. A date in the past is rejected." }, "delivery_options": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/delivery_prediction_option" }, "description": "The carrier and service combinations to predict for. A combination listed more than once is predicted once." } } }, "delivery_prediction": { "title": "delivery_prediction", "type": "object", "description": "ShipStation's own predicted delivery estimate, from its delivery prediction model rather than quoted by the carrier.\n\nThis complements the carrier's own estimate rather than replacing it — where carrier fields are present, they are still populated. The whole object is omitted when a prediction is not available for the carrier, service, and lane, so treat its absence as \"no prediction\" rather than as an error.\n\nTo request predictions on their own, without rating or buying anything, use [Predict delivery dates](#operation/create_delivery_predictions).\n", "additionalProperties": false, "properties": { "delivery_date": { "type": [ "string", "null" ], "format": "date", "readOnly": true, "example": "2026-07-04", "description": "The predicted delivery date." }, "confidence_level": { "type": "string", "readOnly": true, "enum": [ "high", "low" ], "example": "high", "description": "How much historical data the prediction rests on.\n\n- `high` — the prediction is based on historical data for this carrier service.\n- `low` — little or no historical data was available for this service, so the prediction is based on similar services.\n" } } }, "delivery_prediction_result": { "title": "delivery_prediction_result", "type": "object", "description": "A predicted delivery date for one carrier and service combination.", "additionalProperties": false, "properties": { "ship_date": { "type": "string", "format": "date", "readOnly": true, "example": "2026-07-01", "description": "The ship date the prediction was calculated for." }, "delivery_date": { "type": [ "string", "null" ], "format": "date", "readOnly": true, "example": "2026-07-04", "description": "The predicted delivery date." }, "confidence_level": { "type": "string", "readOnly": true, "enum": [ "high", "low" ], "example": "high", "description": "How much historical data the prediction rests on.\n\n- `high` — the prediction is based on historical data for this carrier service.\n- `low` — little or no historical data was available for this service, so the prediction is based on similar services.\n" }, "carrier_details": { "allOf": [ { "$ref": "#/components/schemas/delivery_prediction_carrier_details" } ], "description": "The carrier and service this prediction is for." } } }, "delivery_prediction_warning": { "title": "delivery_prediction_warning", "type": "object", "description": "A requested carrier and service combination that no prediction could be made for.", "additionalProperties": false, "properties": { "carrier_details": { "allOf": [ { "$ref": "#/components/schemas/delivery_prediction_carrier_details" } ], "description": "The carrier and service the warning is about." }, "message": { "type": "string", "readOnly": true, "example": "Carrier and service combination is unsupported.", "description": "Why no prediction was returned for this combination." } } }, "delivery_predictions_response_body": { "title": "delivery_predictions_response_body", "type": "object", "description": "The delivery predictions for the requested lane.\n\nA requested carrier and service combination is never in both arrays: it is either a prediction or a warning. A combination the model returns nothing usable for is in neither, so match on `carrier_details` and treat an absent combination as no prediction being available rather than as an error. When none of the requested combinations is supported, `delivery_predictions` is empty and every combination appears in `warnings`.\n", "additionalProperties": false, "properties": { "delivery_predictions": { "type": "array", "items": { "$ref": "#/components/schemas/delivery_prediction_result" }, "description": "One prediction per supported carrier and service combination." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/delivery_prediction_warning" }, "description": "One entry per requested combination that no prediction could be made for." } } }, "freight_address": { "title": "freight_address", "type": "object", "description": "An origin or destination address for a freight quote. LTL carriers need city, state, postal code, and country to price a shipment — contact and street details are optional at quote time. When booking, use `freight_book_address`, which requires the full contact details needed to produce a Bill of Lading.\n", "additionalProperties": false, "required": [ "city_locality", "state_province", "postal_code", "country_code" ], "properties": { "name": { "type": "string", "example": "Marcus Bell", "description": "The name of the contact person at this location." }, "company_name": { "type": "string", "example": "Northgate Distribution", "description": "The name of the business at this location." }, "address_line1": { "type": "string", "example": "4200 Industrial Pkwy", "description": "The first line of the street address." }, "address_line2": { "type": [ "string", "null" ], "example": "Dock 12", "description": "The second line of the street address, such as a dock or suite number." }, "city_locality": { "type": "string", "example": "Grand Rapids", "description": "The city or locality." }, "state_province": { "type": "string", "example": "MI", "description": "The state or province." }, "postal_code": { "type": "string", "example": "49512", "description": "The postal code." }, "country_code": { "type": "string", "example": "US", "description": "The two-letter ISO 3166-1 alpha-2 country code." }, "phone": { "type": "string", "example": "+1 616 555 0142", "description": "The phone number of the contact person. Carriers call this number to arrange pickup or delivery." }, "email": { "type": [ "string", "null" ], "example": "dock@northgate-dist.example", "description": "The email address of the contact person." }, "location_type": { "type": [ "string", "null" ], "enum": [ "airport", "carrier_terminal", "commercial", "construction", "container_freight_station", "distribution_center", "government_facility", "limited_access", "pier_port_wharf", "residential", "secured_access", "trade_show", null ], "example": "commercial", "description": "How the carrier should classify this location. Location type affects accessorial charges — for example, residential and limited-access locations usually carry a surcharge. An unrecognized value is rejected with a `400 Bad Request`. It describes the kind of site and is independent of the `residential_*` and `construction_site_*` accessorials, so a limited-access destination can also request `residential_delivery`.\n" } } }, "freight_destination_location_type": { "title": "freight_destination_location_type", "type": "object", "description": "The destination of a freight quote that is linked to a shipment with `shipment_id`. The address comes from the shipment, so only `location_type` can be set. It is saved with the shipment's freight configuration and used when you quote or book that shipment again.\n", "additionalProperties": false, "required": [ "location_type" ], "properties": { "location_type": { "type": "string", "enum": [ "airport", "carrier_terminal", "commercial", "construction", "container_freight_station", "distribution_center", "government_facility", "limited_access", "pier_port_wharf", "residential", "secured_access", "trade_show" ], "example": "limited_access", "description": "How the carrier should classify the destination. An unrecognized value is rejected with a `400 Bad Request`.\n" } } }, "freight_book_address": { "title": "freight_book_address", "description": "An origin or destination address for a freight booking. Extends `freight_address` with the contact details — name, company, street, and phone — that the carrier needs to produce a Bill of Lading and to reach the pickup or delivery contact.\n", "allOf": [ { "$ref": "#/components/schemas/freight_address" }, { "type": "object", "required": [ "name", "company_name", "address_line1", "phone" ] } ] }, "freight_tradeshow": { "title": "freight_tradeshow", "type": "object", "description": "Identifies a tradeshow when picking up from or delivering to one.", "additionalProperties": false, "properties": { "name": { "type": "string", "example": "Midwest Home & Garden Expo", "description": "The name of the tradeshow." }, "booth_number": { "type": "string", "example": "B-1147", "description": "The booth number at the tradeshow." } } }, "freight_accessorials": { "title": "freight_accessorials", "type": "object", "description": "Additional services requested from the carrier. Accessorials affect the price of every quote, so request them when you quote — there is no `accessorials` field on the booking request. The offer you book already carries the accessorials it was priced with, so adding one afterwards requires requesting fresh quotes.\n", "additionalProperties": false, "properties": { "liftgate_pickup": { "type": "boolean", "default": false, "example": true, "description": "The origin has no loading dock and the driver needs a liftgate to load the freight." }, "inside_pickup": { "type": "boolean", "default": false, "example": false, "description": "The driver needs to collect the freight from inside the building rather than at the dock or curb." }, "carrier_terminal_pickup": { "type": "boolean", "default": false, "example": false, "description": "The freight is dropped off at the carrier's terminal instead of being collected." }, "grocery_consolidation_pickup": { "type": "boolean", "default": false, "example": false, "description": "The origin is a grocery consolidation facility." }, "residential_pickup": { "type": "boolean", "default": false, "example": false, "description": "The origin is a residential address. This is independent of `ship_from.location_type`, so it can be combined with any location type." }, "construction_site_pickup": { "type": "boolean", "default": false, "example": false, "description": "The origin is a construction site. This is independent of `ship_from.location_type`, so it can be combined with any location type." }, "liftgate_delivery": { "type": "boolean", "default": false, "example": true, "description": "The destination has no loading dock and the driver needs a liftgate to unload the freight." }, "inside_delivery": { "type": "boolean", "default": false, "example": false, "description": "The driver needs to bring the freight inside the building rather than leave it at the dock or curb." }, "appointment_delivery": { "type": "boolean", "default": false, "example": false, "description": "The carrier must schedule a delivery appointment with the consignee." }, "notify_before_delivery": { "type": "boolean", "default": false, "example": true, "description": "The carrier must call the consignee before delivering." }, "hold_at_terminal": { "type": "boolean", "default": false, "example": false, "description": "The carrier holds the freight at the destination terminal for the consignee to collect." }, "grocery_consolidation_delivery": { "type": "boolean", "default": false, "example": false, "description": "The destination is a grocery consolidation facility." }, "residential_delivery": { "type": "boolean", "default": false, "example": true, "description": "The destination is a residential address. This is independent of `ship_to.location_type`, so it can be combined with any location type, such as `limited_access`." }, "construction_site_delivery": { "type": "boolean", "default": false, "example": false, "description": "The destination is a construction site. This is independent of `ship_to.location_type`, so it can be combined with any location type." }, "sort_and_segregate": { "type": "boolean", "default": false, "example": false, "description": "The carrier sorts or segregates the freight on delivery." }, "protection_from_cold": { "type": "boolean", "default": false, "example": false, "description": "The freight must be protected from freezing." }, "protection_from_heat": { "type": "boolean", "default": false, "example": false, "description": "The freight must be protected from heat." }, "tradeshow_pickup": { "allOf": [ { "$ref": "#/components/schemas/freight_tradeshow" } ], "description": "The freight is collected from a tradeshow. Providing this object requests the tradeshow pickup accessorial." }, "tradeshow_delivery": { "allOf": [ { "$ref": "#/components/schemas/freight_tradeshow" } ], "description": "The freight is delivered to a tradeshow. Providing this object requests the tradeshow delivery accessorial." } } }, "freight_insurance": { "title": "freight_insurance", "type": "object", "description": "Requests cargo insurance for the shipment. When present, quotes include the insurance premium and, once bound, a certificate number. Insured values are always in USD.\n", "additionalProperties": false, "required": [ "insured_value" ], "properties": { "insured_value": { "type": "number", "format": "double", "exclusiveMinimum": 0, "example": 18500, "description": "The declared value of the freight to insure, in USD. Must be greater than 0.\n" }, "item_condition": { "type": [ "string", "null" ], "enum": [ "new", "used", null ], "default": "new", "example": "new", "description": "The condition of the insured goods. Maximum liability differs between new and used freight. An unrecognized value is rejected with a `400 Bad Request`.\n" }, "commodity_category": { "type": [ "string", "null" ], "enum": [ "general_merchandise", "equipment", "food_and_beverages", "chemicals", "electronics", "construction_materials", "furniture", "stonework", "fragile", "perishables", "jewelry", "motorized_transportation", "art_and_antiques", "explosives", "life_forms", "controlled_items", "pharmaceuticals_non_refrigerated", "pharmaceuticals_refrigerated", null ], "default": "general_merchandise", "example": "furniture", "description": "The category of the insured goods. Some categories are excluded or restricted by the insurer. An unrecognized value is rejected with a `400 Bad Request`.\n" }, "marks_numbers": { "type": [ "string", "null" ], "example": "NG-2026-0417", "description": "The marks and numbers identifying the insured freight on the shipping documents." } } }, "freight_hazardous_materials": { "title": "freight_hazardous_materials", "type": "object", "description": "Hazardous materials (hazmat) details for a commodity. Providing this object flags the commodity as hazmat, which the carrier prints on the Bill of Lading. All fields other than `subsidiary_hazard_classes`, `emergency_response_reference`, `flashpoint_temperature`, and `additional_details` are required.\n", "additionalProperties": false, "required": [ "identification_number_type", "identification_number", "proper_shipping_name", "hazard_class", "packing_group", "emergency_contact_name", "emergency_contact_phone" ], "properties": { "identification_number_type": { "type": "string", "enum": [ "un", "na" ], "example": "un", "description": "The authority that issued the identification number: `un` for a United Nations number or `na` for a North America number.\n" }, "identification_number": { "type": "string", "maxLength": 50, "example": "UN1263", "description": "The UN or NA number identifying the hazardous material." }, "proper_shipping_name": { "type": "string", "maxLength": 200, "example": "Paint", "description": "The proper shipping name of the hazardous material, as published in the hazardous materials table." }, "hazard_class": { "type": "string", "enum": [ "1.1A", "1.1B", "1.1C", "1.1D", "1.1E", "1.1F", "1.1G", "1.1J", "1.1L", "1.2B", "1.2C", "1.2D", "1.2E", "1.2F", "1.2G", "1.2H", "1.2J", "1.2K", "1.2L", "1.3C", "1.3G", "1.3H", "1.3J", "1.3K", "1.3L", "1.4B", "1.4C", "1.4D", "1.4E", "1.4F", "1.4G", "1.4S", "1.5D", "1.6N", "2.1", "2.2", "2.3", "3", "4.1", "4.2", "4.3", "5.1", "5.2", "6.1", "6.2", "7", "8", "9" ], "example": "3", "description": "The primary hazard class or division of the material." }, "subsidiary_hazard_classes": { "type": "array", "items": { "type": "string", "example": "8" }, "example": [ "8" ], "description": "Any subsidiary hazard classes, using the same values as `hazard_class`. Values must be unique and must not repeat the primary `hazard_class`.\n" }, "packing_group": { "type": "string", "enum": [ "i", "ii", "iii", "none" ], "example": "iii", "description": "The packing group assigned to the material, or `none` when the material has no packing group." }, "emergency_contact_name": { "type": "string", "maxLength": 200, "example": "Chemtrec", "description": "The name of the 24-hour emergency response contact." }, "emergency_contact_phone": { "type": "string", "maxLength": 50, "example": "+1 800 424 9300", "description": "The phone number of the 24-hour emergency response contact." }, "emergency_response_reference": { "type": [ "string", "null" ], "maxLength": 10, "example": "CCN12345", "description": "The emergency response registration or contract number, such as a CHEMTREC contract number." }, "flashpoint_temperature": { "type": [ "number", "null" ], "format": "double", "example": 73, "description": "The flashpoint of the material in degrees Fahrenheit, when it has one." }, "additional_details": { "type": [ "string", "null" ], "maxLength": 250, "example": "Keep upright. Do not stack.", "description": "Any additional hazmat information the carrier should print on the Bill of Lading." } } }, "freight_commodity": { "title": "freight_commodity", "type": "object", "description": "A line of goods inside a handling unit. Every handling unit needs at least one commodity, and each commodity carries its own freight class.\n", "additionalProperties": false, "required": [ "quantity", "weight", "weight_unit", "freight_class" ], "properties": { "description": { "type": [ "string", "null" ], "example": "Assembled oak dining chairs", "description": "A description of the goods. Carriers print this on the Bill of Lading." }, "quantity": { "type": "integer", "format": "int32", "minimum": 1, "example": 24, "description": "The number of pieces of this commodity inside a single handling unit." }, "weight": { "type": "number", "format": "double", "exclusiveMinimum": 0, "example": 310, "description": "The total weight of this commodity line inside a single handling unit." }, "weight_unit": { "allOf": [ { "$ref": "#/components/schemas/weight_unit" } ], "description": "The unit of measure for `weight`." }, "packaging_type": { "type": [ "string", "null" ], "enum": [ "bag", "bale", "box", "bundle", "carton", "case", "crate", "cylinder", "drum", "pail", "pallet", "pieces", "reel", "roll", "skid", "tank", "tote", "trailer", "tube", null ], "example": "carton", "description": "How this commodity is packaged inside the handling unit. Unrecognized values are ignored rather than rejected.\n" }, "freight_class": { "type": "string", "enum": [ "50", "55", "60", "65", "70", "77.5", "85", "92.5", "100", "110", "125", "150", "175", "200", "250", "300", "400", "500" ], "example": "125", "description": "The National Motor Freight Traffic Association (NMFTA) [freight class](https://nmfta.org/nmfc/) of the goods. Freight class is derived from density, stowability, handling, and liability, and is one of the largest factors in the price of an LTL shipment.\n" }, "nmfc_code": { "type": [ "string", "null" ], "example": "80700-2", "description": "The NMFC item and sub number for the goods." }, "hazardous_materials": { "allOf": [ { "$ref": "#/components/schemas/freight_hazardous_materials" } ], "description": "Hazmat details. Provide this object only for hazardous commodities." } } }, "freight_handling_unit": { "title": "freight_handling_unit", "type": "object", "description": "A physical unit the carrier handles, such as a pallet or crate, together with the goods it contains.\n", "additionalProperties": false, "required": [ "quantity", "length", "width", "height", "dimension_unit", "commodities" ], "properties": { "type": { "type": [ "string", "null" ], "enum": [ "bag", "bale", "box", "bundle", "carton", "case", "crate", "cylinder", "drum", "pail", "pallet", "pieces", "reel", "roll", "skid", "tank", "tote", "trailer", "tube", null ], "default": "pallet", "example": "pallet", "description": "The kind of handling unit. Defaults to `pallet`. Unrecognized values are ignored rather than rejected.\n" }, "quantity": { "type": "integer", "format": "int32", "minimum": 1, "example": 2, "description": "The number of identical handling units being shipped. The dimensions, weight, and commodities describe one of them; the carrier multiplies them out.\n" }, "length": { "type": "number", "format": "double", "exclusiveMinimum": 0, "example": 48, "description": "The length of a single handling unit, in the unit specified by `dimension_unit`." }, "width": { "type": "number", "format": "double", "exclusiveMinimum": 0, "example": 40, "description": "The width of a single handling unit, in the unit specified by `dimension_unit`." }, "height": { "type": "number", "format": "double", "exclusiveMinimum": 0, "example": 52, "description": "The height of a single handling unit, in the unit specified by `dimension_unit`." }, "dimension_unit": { "allOf": [ { "$ref": "#/components/schemas/dimension_unit" } ], "description": "The unit of measure for `length`, `width`, and `height`." }, "stackable": { "type": "boolean", "default": false, "example": false, "description": "Whether the carrier may stack other freight on top of this handling unit. Non-stackable freight consumes more trailer space and can cost more.\n" }, "commodities": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/freight_commodity" }, "description": "The goods inside a single handling unit. At least one commodity is required." } } }, "freight_pickup_details": { "title": "freight_pickup_details", "type": "object", "description": "When the carrier can collect the freight. The ready and close times define the pickup window at the origin, and the carrier needs a window wide enough for a driver to arrive.\n", "additionalProperties": false, "required": [ "pickup_date", "ready_time", "close_time" ], "properties": { "pickup_date": { "type": "string", "format": "date", "example": "2026-04-17", "description": "The calendar date at the pickup location when the freight is ready to be collected. Pass a plain date (`YYYY-MM-DD`); any time or UTC offset is accepted but discarded, so `2026-04-17T23:00:00-07:00` and `2026-04-17` both schedule the 17th." }, "ready_time": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "example": "09:00", "description": "The earliest time the freight can be collected, in 24-hour `HH:mm` format and local to the origin." }, "close_time": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "example": "16:30", "description": "The time the origin closes, in 24-hour `HH:mm` format and local to the origin." }, "is_self_scheduled": { "type": "boolean", "default": false, "example": false, "description": "Whether you arrange the pickup with the carrier yourself. When `true`, ShipStation does not request a pickup on your behalf.\n" }, "location_type": { "type": [ "string", "null" ], "enum": [ "airport", "carrier_terminal", "commercial", "construction", "container_freight_station", "distribution_center", "government_facility", "limited_access", "pier_port_wharf", "residential", "secured_access", "trade_show", null ], "example": "commercial", "description": "How the carrier should classify the pickup location. An unrecognized value is rejected with a `400 Bad Request`.\n" } } }, "freight_reference": { "title": "freight_reference", "type": "object", "description": "A reference number the carrier prints on the Bill of Lading, such as a purchase order or sales order number.\n", "additionalProperties": false, "properties": { "type": { "type": [ "string", "null" ], "example": "purchase_order", "description": "A free-form label for the reference, such as `purchase_order`, `sales_order`, or `reference_1`. The values a carrier can print vary by carrier.\n" }, "value": { "type": [ "string", "null" ], "example": "PO-84213", "description": "The reference value. Not length-validated by the API, but keep it short — carriers commonly truncate reference values to around 35 characters on the Bill of Lading.\n" } } }, "freight_provider_account": { "title": "freight_provider_account", "type": "object", "description": "A freight provider account connected to your account.\n", "additionalProperties": false, "properties": { "freight_provider_account_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The identifier of the freight provider account. Pass it as `freight_provider_account_id` when quoting, booking, or tracking.\n" }, "freight_provider_code": { "type": "string", "readOnly": true, "example": "UNISHIPPERS", "description": "The code of the freight provider, such as `UNISHIPPERS` or `WWEX`. This is the same value returned as `freight_provider_code` on quotes, shipments, and tracking.\n" }, "nickname": { "type": [ "string", "null" ], "readOnly": true, "example": "Unishippers - Midwest", "description": "The name given to the connection when it was set up, or `null` when it has none." } } }, "list_freight_provider_accounts_response_body": { "title": "list_freight_provider_accounts_response_body", "type": "object", "description": "The freight provider accounts connected to your account.", "additionalProperties": false, "properties": { "freight_provider_accounts": { "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/freight_provider_account" }, "description": "The active freight provider accounts on the account. An empty array when no freight provider is connected.\n" } } }, "connect_freight_provider_account_request_body": { "title": "connect_freight_provider_account_request_body", "type": "object", "description": "A request to connect a freight account the seller already holds with a provider.\n", "additionalProperties": false, "required": [ "freight_provider_code", "client_id", "client_secret" ], "properties": { "freight_provider_code": { "type": "string", "example": "speedship", "description": "The code of the provider to connect. The connectable codes are the `freight_provider_code` values returned by [List freight provider accounts](#operation/list_freight_provider_accounts). Currently supported: `speedship` (WWEX) and `unishippers`.\n" }, "client_id": { "type": "string", "example": "my-client-id", "description": "The OAuth client ID issued by the freight provider." }, "client_secret": { "type": "string", "example": "my-client-secret", "description": "The OAuth client secret issued by the freight provider." }, "nickname": { "type": [ "string", "null" ], "example": "My WWEX account", "description": "An optional label for the connection. Echoed back by [List freight provider accounts](#operation/list_freight_provider_accounts)." } } }, "update_freight_provider_account_credentials_request_body": { "title": "update_freight_provider_account_credentials_request_body", "type": "object", "description": "A replacement credential pair for a freight provider account. Both fields are required: the pair is replaced atomically, so a partial update is not supported.\n", "additionalProperties": false, "required": [ "client_id", "client_secret" ], "properties": { "client_id": { "type": "string", "example": "my-new-client-id", "description": "The new OAuth client ID issued by the freight provider." }, "client_secret": { "type": "string", "example": "my-new-client-secret", "description": "The new OAuth client secret issued by the freight provider." } } }, "get_freight_quotes_request_body": { "title": "get_freight_quotes_request_body", "type": "object", "description": "A freight quote request. Either describe the shipment inline with `ship_from`, `ship_to`, and `handling_units`, or link it to an existing shipment with `shipment_id`.\n", "additionalProperties": false, "required": [ "freight_provider_account_id" ], "properties": { "freight_provider_account_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The freight provider account to quote against. It must be an active connection on your account — retrieve it with [List freight provider accounts](#operation/list_freight_provider_accounts).\n" }, "shipment_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "An existing shipment to quote for. When provided, the origin is taken from the shipment's ship-from warehouse and the destination from the order's ship-to address, so `ship_from` must be omitted and `ship_to` may contain only `location_type`. The `handling_units`, `accessorials`, `insurance`, and `ship_to.location_type` you send are saved as the shipment's freight configuration; omit them to reuse the configuration already saved.\n" }, "ship_from": { "allOf": [ { "$ref": "#/components/schemas/freight_address" } ], "description": "The origin address. Required when `shipment_id` is omitted, and must not be provided when `shipment_id` is present.\n" }, "ship_to": { "oneOf": [ { "$ref": "#/components/schemas/freight_address" }, { "$ref": "#/components/schemas/freight_destination_location_type" } ], "description": "The destination address. Required when `shipment_id` is omitted. When `shipment_id` is present, the address comes from the shipment and only `location_type` may be provided.\n" }, "shipment_date": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-04-17T00:00:00Z", "description": "The date the freight is ready to ship. Defaults to the current date when omitted." }, "handling_units": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/freight_handling_unit" }, "description": "The handling units being shipped. Required when `shipment_id` is omitted.\n" }, "accessorials": { "allOf": [ { "$ref": "#/components/schemas/freight_accessorials" } ], "description": "Additional services to include in the quote." }, "insurance": { "allOf": [ { "$ref": "#/components/schemas/freight_insurance" } ], "description": "Cargo insurance to quote alongside the freight charges." } } }, "freight_quote": { "title": "freight_quote", "type": "object", "description": "A bookable freight offer from a single LTL carrier.\n", "additionalProperties": false, "properties": { "freight_provider_account_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The freight provider account that returned the offer." }, "freight_provider_code": { "type": "string", "readOnly": true, "example": "UNISHIPPERS", "description": "The code of the freight provider that returned the offer." }, "offer_id": { "type": [ "string", "null" ], "readOnly": true, "example": "0f2b41d8-6a17-4c9e-8f52-b71d3e9c4a68", "description": "Identifies this offer when booking. Resolves server-side to the provider connection, carrier, and expiration — pass this id alone to [Book a freight shipment](#operation/book_freight_shipment).\n" }, "carrier_name": { "type": [ "string", "null" ], "readOnly": true, "example": "FedEx Freight Economy", "description": "The name of the LTL carrier that would move the freight." }, "carrier_scac": { "type": [ "string", "null" ], "readOnly": true, "example": "FXFE", "description": "The Standard Carrier Alpha Code (SCAC) of the LTL carrier." }, "service_name": { "type": [ "string", "null" ], "readOnly": true, "example": "Standard LTL", "description": "The name of the service level the carrier is offering." }, "service_type": { "type": [ "string", "null" ], "readOnly": true, "example": "Direct", "description": "Whether the origin terminal serves the lane directly (`Direct`) or hands the freight to another carrier (`Interline`).\n" }, "total_charges": { "type": "number", "format": "double", "readOnly": true, "example": 842.37, "description": "The total price of the offer in USD, including any accessorials and insurance premium." }, "transit_days": { "type": "integer", "format": "int32", "readOnly": true, "example": 3, "description": "The carrier's estimated number of transit days." }, "estimated_delivery_date": { "type": [ "string", "null" ], "format": "date-time", "readOnly": true, "example": "2026-04-22T00:00:00Z", "description": "The carrier's estimated delivery date, when provided." }, "is_guaranteed": { "type": "boolean", "readOnly": true, "example": false, "description": "Whether the carrier guarantees the transit time for this offer." }, "origin_terminal_code": { "type": [ "string", "null" ], "readOnly": true, "example": "GRR", "description": "The code of the carrier terminal serving the origin." }, "destination_terminal_code": { "type": [ "string", "null" ], "readOnly": true, "example": "DFW", "description": "The code of the carrier terminal serving the destination." }, "insured_amount": { "type": [ "number", "null" ], "format": "double", "readOnly": true, "example": 18500, "description": "The insured value in USD, when insurance was requested." }, "insurance_premium": { "type": [ "number", "null" ], "format": "double", "readOnly": true, "example": 46.25, "description": "The insurance premium in USD included in `total_charges`, when insurance was requested." }, "insurance_certificate_number": { "type": [ "string", "null" ], "readOnly": true, "example": "CRT-4471902", "description": "The insurance certificate number, when the insurer issued one for the offer. `null` when no insurance was requested.\n" }, "quote_expiration_date": { "type": [ "string", "null" ], "format": "date-time", "readOnly": true, "example": "2026-04-16T23:59:59Z", "description": "When the offer expires. Expiry is enforced server-side when booking." }, "max_liability_new": { "type": [ "number", "null" ], "format": "double", "readOnly": true, "example": 25, "description": "The carrier's maximum liability per pound for new goods, in USD. Carrier liability is far below the value of most freight, which is why cargo insurance is usually worth quoting.\n" }, "max_liability_used": { "type": [ "number", "null" ], "format": "double", "readOnly": true, "example": 10, "description": "The carrier's maximum liability per pound for used goods, in USD." } } }, "freight_quotes_response_body": { "title": "freight_quotes_response_body", "type": "object", "description": "The freight offers returned for a quote request.", "additionalProperties": false, "properties": { "quotes": { "type": [ "array", "null" ], "readOnly": true, "items": { "$ref": "#/components/schemas/freight_quote" }, "description": "The offers returned by the provider, one per carrier and service combination. When no carrier can serve the lane as described, this is an empty array or `null`.\n" } } }, "book_freight_shipment_request_body": { "title": "book_freight_shipment_request_body", "type": "object", "description": "A request to book a freight offer returned by a quote. Pass the `offer_id` from the offer being booked — the provider connection, carrier, and expiration are resolved server-side.\n", "additionalProperties": false, "required": [ "offer_id", "pickup_details" ], "properties": { "shipment_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The shipment the offer was quoted for. When provided, the shipment must already have a freight quote, and `ship_from` and `ship_to` must be omitted — the origin, destination, and handling units all come from the shipment and its saved freight configuration.\n" }, "offer_id": { "type": "string", "minLength": 1, "example": "0f2b41d8-6a17-4c9e-8f52-b71d3e9c4a68", "description": "The `offer_id` of the quoted offer being booked. Resolves server-side to the provider connection, the carrier, and the expiration.\n" }, "ship_from": { "allOf": [ { "$ref": "#/components/schemas/freight_book_address" } ], "description": "The origin address. Required when `shipment_id` is omitted, and must not be provided when `shipment_id` is present.\n" }, "ship_to": { "allOf": [ { "$ref": "#/components/schemas/freight_book_address" } ], "description": "The destination address. Required when `shipment_id` is omitted, and must not be provided when `shipment_id` is present.\n" }, "pickup_details": { "allOf": [ { "$ref": "#/components/schemas/freight_pickup_details" } ], "description": "When the carrier can collect the freight. Always required." }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/freight_reference" }, "description": "Reference numbers for the carrier to print on the Bill of Lading." }, "pickup_instructions": { "type": [ "string", "null" ], "example": "Check in with the guard at gate 3 before backing into dock 12.", "description": "Instructions for the driver at the origin." }, "delivery_instructions": { "type": [ "string", "null" ], "example": "Delivery appointments accepted between 08:00 and 11:00 only.", "description": "Instructions for the driver at the destination." }, "handling_instructions": { "type": [ "string", "null" ], "example": "Do not double stack. Load with forks from the long side.", "description": "Instructions for handling the freight in transit." }, "notifications": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/freight_notification" }, "description": "Groups of shipment event notifications to send. Each group names one or more event codes and the email addresses to notify when those events occur. When omitted or `null`, no notifications are sent.\n" } } }, "freight_shipment_status": { "title": "freight_shipment_status", "type": "string", "readOnly": true, "enum": [ "pending", "quoted", "booked", "in_transit", "delivered", "cancelled", "exception" ], "example": "booked", "description": "The lifecycle status of a freight shipment. `exception` is also returned when the status cannot be determined.\n" }, "freight_booked_document": { "title": "freight_booked_document", "type": "object", "description": "A document the carrier generated when the shipment was booked. Each entry includes a `type` and a `url` you can use to download it directly.\n", "additionalProperties": false, "properties": { "type": { "type": "string", "readOnly": true, "example": "BILL_OF_LADING", "description": "The type of document, as reported by the freight provider — for example `BILL_OF_LADING`, `PALLET_LABEL`, or `BOL_PALLET_LABEL_COMBINED`. Unlike the lowercase values returned by [List freight shipment documents](#operation/list_freight_shipment_documents), this is the provider's raw value.\n" }, "url": { "type": [ "string", "null" ], "readOnly": true, "example": "https://api.shipstation.com/v2/downloads/p1/a1b2c3d4e5f6/bill_of_lading.pdf", "description": "The path to download the document as a PDF.\n" } } }, "freight_shipment_document": { "title": "freight_shipment_document", "type": "object", "description": "A document stored for a freight shipment.", "additionalProperties": false, "properties": { "type": { "type": "string", "readOnly": true, "enum": [ "bill_of_lading", "bol_pallet_label_combined", "certificate_of_insurance", "certificate_of_insurance_instructions", "certificate_of_origin_us", "certificate_of_origin_usmca", "certificate_of_origin_usmca_instructions", "international_commercial_invoice", "packing_list", "pallet_label", "pallet_label_4x6", "proof_of_delivery", "quote", "weight_and_inspection" ], "example": "bill_of_lading", "description": "The type of document." }, "url": { "type": [ "string", "null" ], "readOnly": true, "example": "/v2/downloads/10/a1b2c3d4e5f6/bill_of_lading.pdf", "description": "The path to download the document as a PDF, relative to the API host. Resolve it against `https://api.shipstation.com` to get the full URL.\n" } } }, "freight_notification": { "title": "freight_notification", "type": "object", "description": "A group of shipment event notifications. Each group maps one or more event codes to a list of email addresses to notify when those events occur.\n", "additionalProperties": false, "required": [ "events", "email_addresses" ], "properties": { "events": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "quote_ready", "exception", "booked", "delivered", "in_transit", "out_for_delivery", "pickup_scheduled", "voided" ] }, "example": [ "booked", "in_transit" ], "description": "The shipment events that trigger this notification group. Must contain at least one value and no duplicates.\n" }, "email_addresses": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "string", "format": "email" }, "example": [ "logistics@example.com" ], "description": "The email addresses to notify when any of the listed events occur. Between 1 and 5 addresses per group.\n" } } }, "book_freight_shipment_response_body": { "title": "book_freight_shipment_response_body", "type": "object", "description": "The freight shipment created by a booking.", "additionalProperties": false, "properties": { "freight_shipment_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The identifier of the freight shipment. Use it to retrieve, track, or cancel the shipment." }, "shipment_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "type": [ "string", "null" ], "description": "The identifier of the ShipStation shipment linked to this freight booking, if any." }, "freight_provider_account_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The freight provider account the shipment was booked through." }, "freight_provider_code": { "type": "string", "readOnly": true, "example": "UNISHIPPERS", "description": "The code of the freight provider the shipment was booked through." }, "status": { "allOf": [ { "$ref": "#/components/schemas/freight_shipment_status" } ], "description": "The status of the shipment. A successful booking returns `booked`." }, "bol_number": { "type": [ "string", "null" ], "readOnly": true, "example": "BOL-20260417-4821", "description": "The Bill of Lading number assigned to the shipment." }, "pro_number": { "type": [ "string", "null" ], "readOnly": true, "example": "072-51293847", "description": "The carrier's PRO number for the shipment. Carriers often assign this after pickup, so it is usually `null` immediately after booking.\n" }, "confirmation_number": { "type": [ "string", "null" ], "readOnly": true, "example": "FXFE-PU-884215", "description": "The carrier's pickup confirmation number. `null` when the carrier did not return one.\n" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "example": "2026-09-18T14:54:44Z", "description": "The date and time the freight shipment was created, in UTC." }, "documents": { "type": [ "array", "null" ], "readOnly": true, "items": { "$ref": "#/components/schemas/freight_booked_document" }, "description": "The documents the carrier generated for the booking. `null` when the provider reported none.\n" }, "notifications": { "type": [ "array", "null" ], "readOnly": true, "items": { "$ref": "#/components/schemas/freight_notification" }, "description": "The notification groups configured for this shipment, echoed back from the booking request. `null` when no notifications were configured.\n" } } }, "freight_shipment_response_body": { "title": "freight_shipment_response_body", "type": "object", "description": "A freight shipment on your account.", "additionalProperties": false, "properties": { "freight_shipment_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The identifier of the freight shipment." }, "shipment_id": { "anyOf": [ { "$ref": "#/components/schemas/se_id" }, { "type": "null" } ], "example": "se-333551084", "description": "The ID of the base shipment associated with the freight shipment, allowing pairing between standard shipment records and freight shipment records. `null` when no base shipment is associated. This is rare, because a base shipment is created when you book without one." }, "freight_provider_account_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The freight provider account the shipment was booked through." }, "freight_provider_code": { "type": "string", "readOnly": true, "example": "UNISHIPPERS", "description": "The code of the freight provider the shipment was booked through." }, "status": { "allOf": [ { "$ref": "#/components/schemas/freight_shipment_status" } ], "description": "The current status of the shipment." }, "bol_number": { "type": [ "string", "null" ], "readOnly": true, "example": "BOL-20260417-4821", "description": "The Bill of Lading number assigned to the shipment." }, "pro_number": { "type": [ "string", "null" ], "readOnly": true, "example": "072-51293847", "description": "The carrier's PRO number for the shipment, or `null` until the carrier assigns one." }, "confirmation_number": { "type": [ "string", "null" ], "readOnly": true, "example": "FXFE-PU-884215", "description": "The carrier's pickup confirmation number. `null` when the carrier did not return one.\n" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "example": "2026-09-18T14:54:44Z", "description": "The date and time the freight shipment was created, in UTC." }, "documents": { "type": [ "array", "null" ], "readOnly": true, "items": { "$ref": "#/components/schemas/freight_shipment_document" }, "description": "The documents stored for the shipment, each with a download URL. `null` when no documents have been stored yet.\n" }, "notifications": { "type": [ "array", "null" ], "readOnly": true, "items": { "$ref": "#/components/schemas/freight_notification" }, "description": "The notification groups configured for this shipment. `null` when no notifications were configured.\n" } } }, "list_freight_shipments_response_body": { "title": "list_freight_shipments_response_body", "type": "object", "description": "A page of freight shipments.", "additionalProperties": false, "properties": { "shipments": { "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/freight_shipment_response_body" }, "description": "The freight shipments on this page." }, "total": { "type": "integer", "format": "int32", "readOnly": true, "example": 137, "description": "The total number of freight shipments on the account." }, "page": { "type": "integer", "format": "int32", "readOnly": true, "example": 1, "description": "The page of results returned." }, "page_size": { "type": "integer", "format": "int32", "readOnly": true, "example": 25, "description": "The number of freight shipments per page." }, "pages": { "type": "integer", "format": "int32", "readOnly": true, "example": 6, "description": "The total number of pages available." } } }, "cancel_freight_shipment_response_body": { "title": "cancel_freight_shipment_response_body", "type": "object", "description": "The result of cancelling a freight shipment.", "additionalProperties": false, "properties": { "freight_shipment_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The freight shipment that was cancelled." }, "pickup_cancelled": { "type": "boolean", "readOnly": true, "example": true, "description": "`true` when the carrier also voided the associated pickup request. `false` when the shipment had no pickup or the carrier did not confirm the pickup was cancelled.\n" } } }, "freight_document": { "title": "freight_document", "type": "object", "description": "A downloadable document for a freight shipment.", "additionalProperties": false, "properties": { "type": { "type": "string", "readOnly": true, "enum": [ "bill_of_lading", "bol_pallet_label_combined", "certificate_of_insurance", "certificate_of_insurance_instructions", "certificate_of_origin_us", "certificate_of_origin_usmca", "certificate_of_origin_usmca_instructions", "international_commercial_invoice", "packing_list", "pallet_label", "pallet_label_4x6", "proof_of_delivery", "quote", "weight_and_inspection" ], "example": "bill_of_lading", "description": "The type of document." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "readOnly": true, "example": "2026-04-16T14:32:07Z", "description": "When the document was created." }, "url": { "type": [ "string", "null" ], "readOnly": true, "example": "/v2/downloads/10/a1b2c3d4e5f6/bill_of_lading.pdf", "description": "The path to download the document as a PDF, relative to the API host. Resolve it against `https://api.shipstation.com` to get the full URL.\n" } } }, "list_freight_shipment_documents_response_body": { "title": "list_freight_shipment_documents_response_body", "type": "object", "description": "The documents available for a freight shipment.", "additionalProperties": false, "properties": { "documents": { "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/freight_document" }, "description": "The documents available for the shipment. The list grows as the shipment progresses — a proof of delivery, for example, only exists after delivery.\n" } } }, "freight_tracking_event_document": { "title": "freight_tracking_event_document", "type": "object", "description": "A document the carrier attached to a tracking event.", "additionalProperties": false, "properties": { "type": { "type": [ "string", "null" ], "readOnly": true, "example": "PROOF_OF_DELIVERY", "description": "The type of document, as reported by the carrier." }, "filename": { "type": [ "string", "null" ], "readOnly": true, "example": "pod_072-51293847.pdf", "description": "The name of the document file." }, "format": { "type": [ "string", "null" ], "readOnly": true, "example": "PDF", "description": "The file format of the document." } } }, "freight_tracking_event": { "title": "freight_tracking_event", "type": "object", "description": "A single tracking event reported by the carrier.", "additionalProperties": false, "properties": { "occurred_at": { "type": [ "string", "null" ], "readOnly": true, "example": "2026-04-20T14:05:00Z", "description": "When the event occurred, in `YYYY-MM-DDTHH:mm:ssZ` format. Carriers that report only a date return midnight as the time.\n" }, "status": { "type": [ "string", "null" ], "readOnly": true, "example": "in_transit", "description": "The tracking status the event corresponds to." }, "carrier_code": { "type": [ "string", "null" ], "readOnly": true, "example": "AF", "description": "The carrier's own status or event code." }, "description": { "type": [ "string", "null" ], "readOnly": true, "example": "Departed terminal in Grand Rapids, MI", "description": "The carrier's description of the event." }, "documents": { "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/freight_tracking_event_document" }, "description": "Any documents the carrier attached to the event, such as a proof of delivery. Always present; an empty array when the carrier attached none.\n" } } }, "freight_shipment_tracking_response_body": { "title": "freight_shipment_tracking_response_body", "type": "object", "description": "Live carrier tracking for a booked freight shipment.", "additionalProperties": false, "properties": { "freight_shipment_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The freight shipment being tracked." }, "freight_provider_account_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The freight provider account used to retrieve the tracking." }, "freight_provider_code": { "type": "string", "readOnly": true, "example": "UNISHIPPERS", "description": "The code of the freight provider used to retrieve the tracking." }, "carrier_scac": { "type": [ "string", "null" ], "readOnly": true, "example": "FXFE", "description": "The SCAC of the LTL carrier moving the freight." }, "bol_number": { "type": [ "string", "null" ], "readOnly": true, "example": "BOL-20260417-4821", "description": "The Bill of Lading number of the shipment." }, "pro_number": { "type": [ "string", "null" ], "readOnly": true, "example": "072-51293847", "description": "The carrier's PRO number for the shipment, or `null` until the carrier assigns one." }, "status": { "allOf": [ { "$ref": "#/components/schemas/freight_shipment_status" } ], "description": "The shipment status derived from the carrier's tracking status." }, "tracking_status": { "type": [ "string", "null" ], "readOnly": true, "enum": [ "unknown", "created", "pending_pickup", "dispatched", "in_route_to_pickup", "at_pickup", "in_transit", "out_for_delivery", "at_delivery", "delivered", "exception", "voided", null ], "example": "in_transit", "description": "The detailed tracking status reported by the carrier. `tracking_status` is finer-grained than `status`: several tracking statuses, such as `dispatched` and `out_for_delivery`, all map to the `in_transit` shipment status.\n" }, "estimated_delivery_date": { "type": [ "string", "null" ], "readOnly": true, "example": "2026-04-22", "description": "The carrier's estimated delivery date, in `YYYY-MM-DD` format." }, "tracking_url": { "type": [ "string", "null" ], "readOnly": true, "example": "https://www.fedex.com/fedextrack/?trknbr=07251293847", "description": "A carrier page where the shipment can be tracked, when the carrier provides one." }, "last_event_at": { "type": [ "string", "null" ], "readOnly": true, "example": "2026-04-20T14:05:00Z", "description": "When the most recent tracking event occurred." }, "events": { "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/freight_tracking_event" }, "description": "The tracking events reported by the carrier." } } }, "freight_tracking_response_body": { "title": "freight_tracking_response_body", "type": "object", "description": "Live carrier tracking for a PRO or BOL number.", "additionalProperties": false, "properties": { "freight_provider_account_id": { "allOf": [ { "$ref": "#/components/schemas/se_id" } ], "description": "The freight provider account used to retrieve the tracking." }, "freight_provider_code": { "type": "string", "readOnly": true, "example": "UNISHIPPERS", "description": "The code of the freight provider used to retrieve the tracking." }, "carrier_scac": { "type": [ "string", "null" ], "readOnly": true, "example": "FXFE", "description": "The SCAC of the LTL carrier moving the freight, as reported by the carrier. This echoes the provider's response, not the `carrier_scac` you supplied in the request, so it can be `null`.\n" }, "bol_number": { "type": [ "string", "null" ], "readOnly": true, "example": "BOL-20260417-4821", "description": "The Bill of Lading number reported by the carrier." }, "pro_number": { "type": [ "string", "null" ], "readOnly": true, "example": "072-51293847", "description": "The PRO number reported by the carrier." }, "tracking_status": { "type": [ "string", "null" ], "readOnly": true, "enum": [ "unknown", "created", "pending_pickup", "dispatched", "in_route_to_pickup", "at_pickup", "in_transit", "out_for_delivery", "at_delivery", "delivered", "exception", "voided", null ], "example": "delivered", "description": "The detailed tracking status reported by the carrier." }, "tracking_url": { "type": [ "string", "null" ], "readOnly": true, "example": "https://www.fedex.com/fedextrack/?trknbr=07251293847", "description": "A carrier page where the shipment can be tracked, when the carrier provides one." }, "last_event_at": { "type": [ "string", "null" ], "readOnly": true, "example": "2026-04-22T09:41:00Z", "description": "When the most recent tracking event occurred." }, "events": { "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/freight_tracking_event" }, "description": "The tracking events reported by the carrier." } } } }, "responses": { "ServerError": { "description": "An error occurred on ShipStation API's side.", "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": { "freight_shipment_id_path_param": { "name": "freight_shipment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/se_id" }, "example": "se-98765432", "description": "The identifier of the freight shipment." }, "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" }, "tag_query_param": { "name": "tag", "in": "query", "required": false, "description": "Filter shipments by tag name. Returns only shipments that have been assigned the specified tag. You can filter by one tag at a time. Tags are arbitrary strings used to categorize shipments (e.g., \"Priority\", \"Fragile\", \"International\").", "schema": { "$ref": "#/components/schemas/tag_name" } }, "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" }, "document_id_path_param": { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the document.", "example": "7f3c1b2a-9d4e-4f5a-8c6b-2e1d0a9b8c7d" }, "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", "description": "Filter labels by external shipment ID." }, "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" }, "manifest_request_id_path_param": { "name": "manifest_request_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/se_id" }, "description": "The Manifest Request 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_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" }, "description": "The rate selection strategy or custom rate shopper ID.\n\n**Standard strategies:**\n- `cheapest`: Lowest cost option\n- `fastest`: Fastest option at the lowest price\n- `best_value`: Lowest cost option arriving within 4 days\n\n**Custom rate shopper:**\nPass a service collection GUID (e.g., `f47ac10b-58cc-4372-a567-0e02b2c3d479`)\nto use a custom rate shopper configuration. The service collection must be\nactive and owned by the authenticated seller.\n", "examples": { "standard": { "value": "cheapest", "summary": "Standard strategy using the cheapest option" }, "custom": { "value": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "summary": "Custom rate shopper using a service collection GUID" } } }, "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" } } } }