{ "openapi": "3.0.3", "info": { "title": "Shipping Hub REST API", "version": "1.0.0", "description": "Automate everything you can do in the Shipping Hub UI \u2014 orders, live rates, labels, shipments, batches, customers, products, inventory and reports.\n\nAuthenticate every call with a single API key created in Settings \u2192 API. Send it as `Authorization: Bearer `, the `X-API-Key` header, or `?api_key=`." }, "servers": [ { "url": "https://api.arub.com" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] }, { "apiKeyQuery": [] } ], "tags": [ { "name": "Meta" }, { "name": "Orders" }, { "name": "Rates & Labels" }, { "name": "Shipments" }, { "name": "Batches" }, { "name": "Customers" }, { "name": "Products" }, { "name": "Inventory" }, { "name": "Tags & Settings" }, { "name": "Reference" }, { "name": "Reports" } ], "paths": { "/v1/ping": { "get": { "tags": [ "Meta" ], "summary": "Health check \u2014 verifies your API key works", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/me": { "get": { "tags": [ "Meta" ], "summary": "Account info: instance, client, connected carriers, order counts", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/orders": { "get": { "tags": [ "Orders" ], "summary": "List orders", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "awaiting_shipment, on_hold, shipped, cancelled, \u2026" }, { "name": "channel", "in": "query", "schema": { "type": "string" }, "description": "Sales-channel id (0 = Manual)" }, { "name": "tag", "in": "query", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ] }, "post": { "tags": [ "Orders" ], "summary": "Create an order", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreate" } } } } } }, "/v1/orders/bulk": { "post": { "tags": [ "Orders" ], "summary": "Bulk action (status|tag|preset|hold|mark-shipped|merge)", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/orders/{id}": { "get": { "tags": [ "Orders" ], "summary": "Get one order with items, shipments and tags", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/orders/{id}/history": { "get": { "tags": [ "Orders" ], "summary": "Order change history", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/orders/{id}/address": { "put": { "tags": [ "Orders" ], "summary": "Update the shipping address", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/orders/{id}/package": { "put": { "tags": [ "Orders" ], "summary": "Update size / weight / package type", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/orders/{id}/notes": { "put": { "tags": [ "Orders" ], "summary": "Update internal/customer notes", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/orders/{id}/status": { "post": { "tags": [ "Orders" ], "summary": "Set status (supports hold_until for on_hold)", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/orders/{id}/tags": { "post": { "tags": [ "Orders" ], "summary": "Add a tag {tag_id}", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/orders/{id}/tags/{tag}": { "delete": { "tags": [ "Orders" ], "summary": "Remove a tag", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "tag", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/orders/{id}/mark-shipped": { "post": { "tags": [ "Orders" ], "summary": "Manually mark shipped {carrier, tracking}", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/orders/{id}/duplicate": { "post": { "tags": [ "Orders" ], "summary": "Duplicate the order", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/orders/{id}/merge": { "post": { "tags": [ "Orders" ], "summary": "Merge another order into this one {source_id | source_number}", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/orders/{id}/split": { "post": { "tags": [ "Orders" ], "summary": "Split items onto a new order {item_ids:[], quantities:{item_id:units}} \u2014 quantities is optional; a mapped line moves only that many units and the source keeps the rest", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/orders/{id}/items/{item}/rename": { "post": { "tags": [ "Orders" ], "summary": "Rename an order item {name, scope}", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "item", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/orders/{id}/rates": { "post": { "tags": [ "Rates & Labels" ], "summary": "Get live carrier rates for the order", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/orders/{id}/label": { "post": { "tags": [ "Rates & Labels" ], "summary": "Buy a label {rate_id, signature?, insure?, \u2026}", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyLabel" } } } } } }, "/v1/shipments": { "get": { "tags": [ "Shipments" ], "summary": "List shipments (labels) by bucket + date range", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "bucket", "in": "query", "schema": { "type": "string", "enum": [ "recent", "in_transit", "delivered", "exceptions", "voided" ] } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ] } }, "/v1/shipments/{id}": { "get": { "tags": [ "Shipments" ], "summary": "Get one shipment", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/shipments/{id}/label": { "get": { "tags": [ "Shipments" ], "summary": "Download the label (binary; add ?encode=base64 for JSON)", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/shipments/{id}/track": { "get": { "tags": [ "Shipments" ], "summary": "Live carrier tracking", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/shipments/{id}/void": { "post": { "tags": [ "Shipments" ], "summary": "Void the label", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/shipments/{id}/delivered": { "post": { "tags": [ "Shipments" ], "summary": "Mark the shipment delivered", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/batches": { "get": { "tags": [ "Batches" ], "summary": "List batches (optionally ?status=open|ready|closed)", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } }, "post": { "tags": [ "Batches" ], "summary": "Create a batch {name}", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/batches/{id}": { "get": { "tags": [ "Batches" ], "summary": "Get a batch and its orders", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/batches/{id}/orders": { "post": { "tags": [ "Batches" ], "summary": "Add orders {order_id | ids:[]}", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/batches/{id}/orders/{order}": { "delete": { "tags": [ "Batches" ], "summary": "Remove an order from the batch", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "order", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/batches/{id}/status": { "post": { "tags": [ "Batches" ], "summary": "Set batch status {status}", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/batches/{id}/buy": { "post": { "tags": [ "Batches" ], "summary": "Run the batch: buy each order's already-quoted cheapest rate; orders that cannot ship are removed from the batch. An order that already has a live label is removed too unless confirm_extra_label is sent, since buying it again is a second charge", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyBatch" } } } } } }, "/v1/batches/{id}/pdf": { "get": { "tags": [ "Batches" ], "summary": "Download combined slips + labels PDF", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/customers": { "get": { "tags": [ "Customers" ], "summary": "List customers", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ] }, "post": { "tags": [ "Customers" ], "summary": "Create a customer", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/customers/{id}": { "get": { "tags": [ "Customers" ], "summary": "Get a customer with order history + tags", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] }, "put": { "tags": [ "Customers" ], "summary": "Update a customer", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] }, "delete": { "tags": [ "Customers" ], "summary": "Delete a customer", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/customers/{id}/merge": { "post": { "tags": [ "Customers" ], "summary": "Merge this customer into {target_id}", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/customers/{id}/tags": { "post": { "tags": [ "Customers" ], "summary": "Add a tag {tag_id}", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/customers/{id}/tags/{tag}": { "delete": { "tags": [ "Customers" ], "summary": "Remove a tag", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "tag", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/products": { "get": { "tags": [ "Products" ], "summary": "List products (per-SKU master name + picture)", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ] }, "post": { "tags": [ "Products" ], "summary": "Add a product {sku, name}", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/products/{id}": { "get": { "tags": [ "Products" ], "summary": "Get a product", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] }, "put": { "tags": [ "Products" ], "summary": "Rename {name, cascade?}", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] }, "delete": { "tags": [ "Products" ], "summary": "Delete a product", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/products/{id}/image": { "get": { "tags": [ "Products" ], "summary": "Download the packing-slip picture (JPEG)", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] }, "post": { "tags": [ "Products" ], "summary": "Set the picture {image_base64}", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] }, "delete": { "tags": [ "Products" ], "summary": "Clear the picture", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/products/{id}/image/recache": { "post": { "tags": [ "Products" ], "summary": "Re-pull the picture from the order image", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/inventory/items": { "get": { "tags": [ "Inventory" ], "summary": "List inventory items", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } }, "post": { "tags": [ "Inventory" ], "summary": "Create an item", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/inventory/items/{id}": { "get": { "tags": [ "Inventory" ], "summary": "Get an item + its locations", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] }, "put": { "tags": [ "Inventory" ], "summary": "Update an item", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] }, "delete": { "tags": [ "Inventory" ], "summary": "Delete an item", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/inventory/items/{id}/stock": { "post": { "tags": [ "Inventory" ], "summary": "Set stock {set} or change it {adjust}", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/inventory/locations": { "get": { "tags": [ "Inventory" ], "summary": "List locations", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } }, "post": { "tags": [ "Inventory" ], "summary": "Create a location {name}", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/inventory/types": { "get": { "tags": [ "Inventory" ], "summary": "List item types", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/inventory/subtypes": { "get": { "tags": [ "Inventory" ], "summary": "List item subtypes", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/inventory/purchases": { "get": { "tags": [ "Inventory" ], "summary": "List purchase (on-order) records", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } }, "post": { "tags": [ "Inventory" ], "summary": "Create a purchase", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/inventory/purchases/{id}": { "put": { "tags": [ "Inventory" ], "summary": "Update a purchase", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] }, "delete": { "tags": [ "Inventory" ], "summary": "Delete a purchase", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/inventory/purchases/{id}/receive": { "post": { "tags": [ "Inventory" ], "summary": "Mark a purchase received", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/inventory/factories": { "get": { "tags": [ "Inventory" ], "summary": "List factories", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } }, "post": { "tags": [ "Inventory" ], "summary": "Create a factory {name}", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/tags": { "get": { "tags": [ "Tags & Settings" ], "summary": "List tags", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } }, "post": { "tags": [ "Tags & Settings" ], "summary": "Create a tag", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/tags/{id}": { "put": { "tags": [ "Tags & Settings" ], "summary": "Update a tag", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] }, "delete": { "tags": [ "Tags & Settings" ], "summary": "Delete a tag", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/presets": { "get": { "tags": [ "Tags & Settings" ], "summary": "List presets", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } }, "post": { "tags": [ "Tags & Settings" ], "summary": "Create a preset", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/presets/{id}": { "put": { "tags": [ "Tags & Settings" ], "summary": "Update a preset", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] }, "delete": { "tags": [ "Tags & Settings" ], "summary": "Delete a preset", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/rate-rules": { "get": { "tags": [ "Tags & Settings" ], "summary": "List rate rules", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } }, "post": { "tags": [ "Tags & Settings" ], "summary": "Create a rate rule", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/rate-rules/{id}": { "put": { "tags": [ "Tags & Settings" ], "summary": "Update a rate rule", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] }, "delete": { "tags": [ "Tags & Settings" ], "summary": "Delete a rate rule", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/order-rules": { "get": { "tags": [ "Tags & Settings" ], "summary": "List order (auto-tag) rules", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } }, "post": { "tags": [ "Tags & Settings" ], "summary": "Create an order rule", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/order-rules/{id}": { "put": { "tags": [ "Tags & Settings" ], "summary": "Update an order rule", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] }, "delete": { "tags": [ "Tags & Settings" ], "summary": "Delete an order rule", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/v1/settings/return-address": { "get": { "tags": [ "Tags & Settings" ], "summary": "Get the ship-from address", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } }, "put": { "tags": [ "Tags & Settings" ], "summary": "Update the ship-from address", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/settings/rate-timeout": { "get": { "tags": [ "Tags & Settings" ], "summary": "Get the rate timeout (ms)", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } }, "put": { "tags": [ "Tags & Settings" ], "summary": "Set the rate timeout {ms}", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/settings/packages": { "get": { "tags": [ "Tags & Settings" ], "summary": "List carrier package types", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/settings/packages/{id}": { "put": { "tags": [ "Tags & Settings" ], "summary": "Enable/disable a package type {enabled}", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Package type key, e.g. usps:FLAT_RATE_ENVELOPE (from GET /v1/settings/packages)" } ] } }, "/v1/carriers": { "get": { "tags": [ "Reference" ], "summary": "List connected carriers (read-only)", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/channels": { "get": { "tags": [ "Reference" ], "summary": "List sales channels (read-only)", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/reports": { "get": { "tags": [ "Reports" ], "summary": "List available reports", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } } } }, "/v1/reports/{key}": { "get": { "tags": [ "Reports" ], "summary": "Get one report over a date range", "responses": { "200": { "description": "Success" }, "401": { "description": "Missing or invalid API key" }, "422": { "description": "Validation error" } }, "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "page", "in": "query", "description": "Page of the report table, where it has one.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "description": "Rows per page. Anything not on the offered scale falls back to 50.", "schema": { "type": "integer", "enum": [ 25, 50, 75, 100, 125, 150, 175, 200 ], "default": 50 } }, { "name": "status", "in": "query", "description": "Narrow a shipment table to one status, e.g. pre_transit. Unknown values return every row.", "schema": { "type": "string" } } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "apiKeyQuery": { "type": "apiKey", "in": "query", "name": "api_key" } }, "schemas": { "OrderCreate": { "type": "object", "required": [ "name", "street1", "city", "state", "postal" ], "properties": { "integration": { "type": "integer", "description": "Channel id (0 = Manual)" }, "number": { "type": "string" }, "order_date": { "type": "string", "format": "date" }, "name": { "type": "string" }, "company": { "type": "string" }, "street1": { "type": "string" }, "street2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal": { "type": "string" }, "country": { "type": "string", "default": "US" }, "phone": { "type": "string" }, "email": { "type": "string" }, "gift": { "type": "integer" }, "gift_note": { "type": "string" }, "notes_internal": { "type": "string" }, "notes_customer": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "sku": { "type": "string" }, "quantity": { "type": "integer" }, "price": { "type": "number" } } } } } }, "BuyLabel": { "type": "object", "required": [ "rate_id" ], "properties": { "rate_id": { "type": "string", "description": "One of the rate_id values returned by POST /orders/{id}/rates" }, "signature": { "type": "integer", "enum": [ 0, 1 ] }, "adult_signature": { "type": "integer", "enum": [ 0, 1 ] }, "insure": { "type": "integer", "enum": [ 0, 1 ] }, "certified_mail": { "type": "integer", "enum": [ 0, 1 ] }, "return_receipt": { "type": "integer", "enum": [ 0, 1 ] } } }, "BuyBatch": { "type": "object", "properties": { "confirm_extra_label": { "type": "boolean", "default": false, "description": "Buy a label for an order that already has a live one (a reship). Without this, such an order is taken out of the batch and listed in `removed` instead of being charged for twice." } } }, "Envelope": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }