{ "openapi": "3.1.0", "info": { "title": "Conveyr", "description": "Conveyr API", "version": "1.0.0", "contact": { "name": "Conveyr Support", "email": "support@prepbusiness.com", "url": "https://prepbusiness.com" } }, "servers": [ { "url": "https://app.prepbusiness.com/api", "description": "Production server" } ], "paths": { "/channels": { "get": { "summary": "List channels", "operationId": "list-channels", "tags": [ "Channels" ], "responses": { "200": { "description": "A successful response returning the list of channels", "content": { "application/json": { "schema": { "type": "object", "properties": { "channels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier for the channel", "example": 1 }, "merchant_id": { "type": "integer", "description": "The ID of the merchant that owns the channel", "example": 1 }, "type": { "type": "string", "description": "The type of the channel", "example": "amazon" }, "nickname": { "type": [ "string", "null" ], "description": "An optional nickname for the channel" }, "channel_account_id": { "type": [ "string", "null" ], "description": "The account ID used to identify the channel on the external platform" }, "connection_status": { "type": "string", "description": "The current connection status of the channel", "example": "active" }, "country_id": { "type": [ "integer", "string", "null" ], "description": "The country ID associated with the channel, if any" }, "team_id": { "type": "integer", "description": "Alias for merchant_id" } }, "additionalProperties": false, "required": [ "id", "merchant_id", "team_id", "type", "nickname", "channel_account_id", "connection_status", "country_id" ] } } }, "required": [ "channels" ] }, "examples": { "example": { "value": { "channels": [ { "id": 2, "merchant_id": 2, "team_id": 2, "type": "amazon", "nickname": "Amazon Store", "channel_account_id": "23o-othvv-xkrxh-rlrw", "connection_status": "active", "country_id": "ATVPDKIKX0DER" } ] } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" } } } }, "/channels/{channel_id}/listings": { "get": { "summary": "List listings for a channel", "operationId": "list-channel-listings", "tags": [ "Channels" ], "parameters": [ { "name": "channel_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the channel", "example": 1 } } ], "responses": { "200": { "description": "A successful response returning the paginated list of listings", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/paths/~1inventory/get/responses/200/content/application~1json/schema/allOf/0" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/paths/~1channels~1%7Bchannel_id%7D~1listings/post/responses/201/content/application~1json/schema/properties/data" } } }, "required": [ "data" ] } ] }, "examples": { "example": { "value": { "data": [ { "id": 21, "created_at": "2025-03-10T04:02:47Z", "updated_at": "2025-03-10T09:22:27Z", "channel_id": 1, "sku": "Digital-A-433828", "title": "Digital Alarm Clock", "condition": null, "condition_note": null, "channel_identifier": "Digital-A-433828", "length_mm": null, "width_mm": null, "height_mm": null, "weight_gm": null, "status": "synced", "flags": [], "identifiers": [ { "id": 61, "listing_id": 21, "identifier": "6619524668697", "type": "EAN" } ], "images": [], "seller_listing_details_updated_at": null, "catalog_details_updated_at": null, "product_link": { "id": 175, "created_at": "2025-03-12T07:11:44Z", "listing_id": 21, "product_id": 21, "product_uuid": "550e8400-e29b-41d4-a716-446655440000" } } ], "total": 2, "current_page": 1, "last_page": 1, "per_page": 20, "from": 1, "to": 2 } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" } } }, "post": { "summary": "Create a listing for a channel", "operationId": "create-channel-listing", "tags": [ "Channels" ], "parameters": [ { "name": "channel_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the channel", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel_identifier": { "type": "string", "description": "The channel-specific identifier for the listing (e.g. ASIN for Amazon)", "example": "B01234567" }, "item_id": { "type": "integer", "description": "The ID of the inventory item to link to this listing", "example": 1 }, "merchant_sku": { "type": [ "string", "null" ], "description": "The merchant SKU to use for this listing. If omitted, the item's SKU will be used." }, "condition": { "type": [ "string", "null" ], "description": "The condition of the listed item" } }, "required": [ "channel_identifier", "item_id" ] } } } }, "responses": { "201": { "description": "A successful response returning the created listing", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier for the listing", "example": 1 }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the listing was created", "example": "2024-01-01T00:00:00Z" }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the listing was last updated", "example": "2024-01-01T00:00:00Z" }, "channel_id": { "type": "integer", "description": "The ID of the channel this listing belongs to", "example": 1 }, "sku": { "type": [ "string", "null" ], "description": "The merchant SKU for this listing" }, "title": { "type": [ "string", "null" ], "description": "The title of the listing" }, "condition": { "type": [ "string", "null" ], "description": "The condition of the listed item" }, "condition_note": { "type": [ "string", "null" ], "description": "A note describing the condition of the listed item" }, "channel_identifier": { "type": "string", "description": "The identifier used by the channel to identify this listing (e.g. ASIN for Amazon)", "example": "B01234567" }, "length_mm": { "type": [ "integer", "null" ], "description": "The length of the item in millimetres" }, "width_mm": { "type": [ "integer", "null" ], "description": "The width of the item in millimetres" }, "height_mm": { "type": [ "integer", "null" ], "description": "The height of the item in millimetres" }, "weight_gm": { "type": [ "integer", "null" ], "description": "The weight of the item in grams" }, "status": { "type": "string", "description": "The current sync status of the listing", "enum": [ "unsynced", "submitted", "checking", "synced" ], "example": "synced" }, "flags": { "type": [ "array", "null" ], "description": "Any flags associated with the listing", "items": {} }, "identifiers": { "type": "array", "description": "The identifiers associated with this listing", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "listing_id": { "type": "integer", "example": 1 }, "identifier": { "type": "string", "example": "X000ABCDEF" }, "type": { "type": "string", "example": "FNSKU" } }, "additionalProperties": false, "required": [ "id", "listing_id", "identifier", "type" ] } }, "images": { "type": "array", "description": "The images associated with this listing", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "listing_id": { "type": "integer", "example": 1 }, "large_url": { "type": "string", "example": "https://example.com/image.jpg" }, "thumbnail_url": { "type": "string", "example": "https://example.com/thumbnail.jpg" } }, "additionalProperties": false, "required": [ "id", "listing_id", "large_url", "thumbnail_url" ] } }, "product_link": { "type": [ "object", "null" ], "description": "The product link associating this listing to a product", "properties": { "id": { "type": "integer", "example": 1 }, "created_at": { "type": "string", "example": "2024-01-01T00:00:00Z" }, "listing_id": { "type": "integer", "example": 1 }, "product_id": { "type": "integer", "example": 1 }, "product_uuid": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } }, "required": [ "id", "created_at", "listing_id", "product_id", "product_uuid" ] }, "seller_listing_details_updated_at": { "type": [ "string", "null" ], "description": "The date when seller listing details were last updated" }, "catalog_details_updated_at": { "type": [ "string", "null" ], "description": "The date when catalog details were last updated" } }, "additionalProperties": false, "required": [ "id", "created_at", "updated_at", "channel_id", "sku", "title", "condition", "condition_note", "channel_identifier", "length_mm", "width_mm", "height_mm", "weight_gm", "status", "flags", "identifiers", "images", "seller_listing_details_updated_at", "catalog_details_updated_at" ] } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "id": 1485, "created_at": "2025-03-12T09:01:36Z", "updated_at": "2025-03-12T09:01:36Z", "channel_id": 1, "sku": "Rotating-M-949927", "title": "Rotating Makeup Organizer", "condition": null, "condition_note": null, "channel_identifier": "Rotating-M-9499272", "length_mm": null, "width_mm": null, "height_mm": null, "weight_gm": null, "status": "checking", "flags": [], "identifiers": [], "images": [], "seller_listing_details_updated_at": null, "catalog_details_updated_at": null, "product_link": null } } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/channels/listings/{listing}/link": { "post": { "summary": "Link a listing to a product", "operationId": "link-listing-to-product", "tags": [ "Channels" ], "parameters": [ { "name": "listing", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the listing", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "item_id": { "type": "integer", "description": "The ID of the inventory item to link to this listing", "example": 1 } }, "required": [ "item_id" ] } } } }, "responses": { "200": { "description": "A successful response indicating the listing was linked", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Listing linked to item" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Listing linked to item" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/billing/charges": { "get": { "summary": "List charges", "operationId": "list-charges", "tags": [ "Billing" ], "responses": { "200": { "description": "A successful response returning the paginated list of charges", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/paths/~1inventory/get/responses/200/content/application~1json/schema/allOf/0" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/paths/~1billing~1charges~1%7Bcharge%7D/get/responses/200/content/application~1json/schema/properties/charge" } } }, "required": [ "data" ] } ] }, "examples": { "example": { "value": { "data": [ { "id": 11, "charger_id": 8617, "charger_type": "company", "chargee_id": 6320, "chargee_type": "team", "created_at": "2026-01-08T16:42:25.943180Z", "currency": "USD", "price": 521, "status": "Invoiced", "category": "OutboundShipment", "description": "Services charges for outbound shipment: Quantum Dynamics.", "amount": 521, "stripe_invoice_item_id": null } ], "total": 11, "current_page": 1, "last_page": 2, "per_page": 10, "from": 0, "to": 10 } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" } } } }, "/billing/charges/{charge}": { "get": { "summary": "Show a charge", "operationId": "show-charge", "tags": [ "Billing" ], "parameters": [ { "name": "charge", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the charge", "example": 1 } } ], "responses": { "200": { "description": "A successful response returning the charge and its items", "content": { "application/json": { "schema": { "type": "object", "properties": { "charge": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier for the charge", "example": 1 }, "charger_id": { "type": "integer", "description": "The ID of the service provider that issued the charge", "example": 1 }, "charger_type": { "type": "string", "description": "The type of the charger entity", "example": "company" }, "chargee_id": { "type": "integer", "description": "The ID of the merchant being charged", "example": 1 }, "chargee_type": { "type": "string", "description": "The type of the chargee entity", "example": "team" }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the charge was created", "example": "2024-01-01T00:00:00Z" }, "currency": { "type": "string", "description": "The ISO 4217 currency code", "example": "USD" }, "price": { "type": "number", "description": "The price of the charge", "example": 9.99 }, "status": { "type": "string", "description": "The current status of the charge", "example": "pending" }, "category": { "type": [ "string", "null" ], "description": "The category of the charge" }, "description": { "type": [ "string", "null" ], "description": "A description of the charge" }, "amount": { "type": "number", "description": "The total amount of the charge", "example": 9.99 }, "stripe_invoice_item_id": { "type": [ "string", "null" ], "description": "The Stripe invoice item ID associated with the charge" } }, "additionalProperties": false, "required": [ "id", "charger_id", "charger_type", "chargee_id", "chargee_type", "created_at", "currency", "price", "status", "amount" ] }, "charge_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier for the charge item", "example": 1 }, "charge_id": { "type": "integer", "description": "The ID of the parent charge", "example": 1 }, "parent_id": { "type": [ "integer", "null" ], "description": "The ID of the parent charge item, if any" }, "chargeable_item": { "type": [ "object", "null" ], "description": "The chargeable item associated with this charge item", "properties": { "id": { "type": "integer", "description": "The ID of the chargeable item" }, "description": { "type": "string", "description": "The description of the chargeable item" } }, "required": [ "id", "description" ] }, "chargeable_item_id": { "type": [ "integer", "null" ], "description": "The ID of the associated chargeable item" }, "chargeable_item_type": { "type": [ "string", "null" ], "description": "The type/class of the associated chargeable item" }, "description": { "type": [ "string", "null" ], "description": "A description of the charge item" }, "is_amendment": { "type": "boolean", "description": "Whether this charge item is an amendment" }, "units": { "type": "number", "description": "The number of units", "example": 1 }, "unit_price_amount": { "type": "number", "description": "The price per unit", "example": 9.99 }, "line_price_amount": { "type": "number", "description": "The total line price (units * unit_price_amount)", "example": 9.99 } }, "required": [ "id", "charge_id", "parent_id", "chargeable_item", "chargeable_item_id", "chargeable_item_type", "description", "is_amendment", "units", "unit_price_amount", "line_price_amount" ] } } }, "required": [ "charge", "charge_items" ] }, "examples": { "example": { "value": { "charge": { "id": 67, "charger_id": 1, "charger_type": "company", "chargee_id": 1, "chargee_type": "team", "created_at": "2023-08-31T14:00:39.000000Z", "currency": "USD", "price": 1.24, "status": "Open", "category": "OutboundShipment", "description": "Services charges for outbound shipment (FBA ID: FBA0LUMFEZQ3W): receive outbound.", "amount": 1.24, "stripe_invoice_item_id": null }, "charge_items": [ { "id": 901, "charge_id": 67, "parent_id": null, "chargeable_item": null, "chargeable_item_id": 66, "chargeable_item_type": "outbound-shipment", "description": "Outbound Shipment, FBA ID: FBA0LUMFEZQ3W", "is_amendment": false, "units": 1, "unit_price_amount": 0, "line_price_amount": 0 } ] } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" } } } }, "/billing/charges/quick-adjustment": { "post": { "summary": "Store a quick adjustment charge", "operationId": "store-quick-adjustment", "tags": [ "Billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "The amount of the adjustment", "example": 9.99 }, "description": { "type": "string", "description": "A description of the adjustment", "example": "Monthly fee adjustment" } }, "required": [ "amount", "description" ] } } } }, "responses": { "201": { "description": "A successful response returning the created charge and its items", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A success message", "example": "Adjustment charged to client account." }, "charge": { "$ref": "#/paths/~1billing~1charges~1%7Bcharge%7D/get/responses/200/content/application~1json/schema/properties/charge" }, "charge_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "charge_id": { "type": "integer", "example": 1 }, "parent_id": { "type": [ "integer", "null" ] }, "chargeable_item": { "type": [ "object", "null" ] }, "chargeable_item_id": { "type": [ "integer", "null" ] }, "chargeable_item_type": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "is_amendment": { "type": "boolean" }, "units": { "type": "number", "example": 1 }, "unit_price_amount": { "type": "number", "example": 9.99 }, "line_price_amount": { "type": "number", "example": 9.99 } }, "required": [ "id", "charge_id", "parent_id", "chargeable_item", "chargeable_item_id", "chargeable_item_type", "description", "is_amendment", "units", "unit_price_amount", "line_price_amount" ] } } }, "required": [ "message", "charge", "charge_items" ] }, "examples": { "example": { "value": { "message": "Adjustment charged to client account.", "charge": { "id": 307, "charger_id": 1, "charger_type": "company", "chargee_id": 1, "chargee_type": "team", "created_at": "2024-05-21T18:50:31.496429Z", "currency": "USD", "price": 10, "status": "Open", "category": "Adjustment", "description": "Storage", "amount": 10, "stripe_invoice_item_id": null }, "charge_items": [ { "id": 1093, "charge_id": 307, "parent_id": null, "chargeable_item": null, "chargeable_item_id": null, "chargeable_item_type": null, "description": "Storage", "is_amendment": false, "units": 1, "unit_price_amount": 10, "line_price_amount": 10 } ] } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/billing/invoices": { "get": { "summary": "List invoices", "operationId": "list-invoices", "tags": [ "Billing" ], "responses": { "200": { "description": "A successful response returning the paginated list of invoices", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/paths/~1inventory/get/responses/200/content/application~1json/schema/allOf/0" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/paths/~1billing~1invoices/post/responses/200/content/application~1json/schema/properties/invoice" } } }, "required": [ "data" ] } ] }, "examples": { "example": { "value": { "data": [ { "id": 129, "charger_id": 8617, "charger_type": "company", "chargee_id": 6320, "chargee_type": "team", "created_at": "2026-01-08T17:20:05Z", "currency": "USD", "status": "Draft", "stripe_invoice_status": null, "stripe_invoice_id": null, "description": null, "total": 257.75, "stripe_automatic_tax": { "enabled": null } } ], "total": 2, "current_page": 1, "last_page": 1, "per_page": 10, "from": 0, "to": 10 } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" } } }, "post": { "summary": "Create an invoice", "operationId": "create-invoice", "tags": [ "Billing" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "charge_ids": { "type": "array", "description": "Optional array of charge IDs to include in the invoice. If omitted, all uninvoiced charges will be included.", "items": { "type": "integer" } } } } } } }, "responses": { "200": { "description": "A successful response returning the created invoice", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Draft invoice created." }, "invoice": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier for the invoice", "example": 1 }, "charger_id": { "type": "integer", "description": "The ID of the service provider that issued the invoice", "example": 1 }, "charger_type": { "type": "string", "description": "The type of the charger entity", "example": "company" }, "chargee_id": { "type": "integer", "description": "The ID of the merchant being invoiced", "example": 1 }, "chargee_type": { "type": "string", "description": "The type of the chargee entity", "example": "team" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp of when the invoice was created", "example": "2024-01-01T00:00:00Z" }, "currency": { "type": "string", "description": "The ISO 4217 currency code", "example": "USD" }, "status": { "type": "string", "description": "The current status of the invoice", "example": "draft" }, "stripe_invoice_status": { "type": [ "string", "null" ], "description": "The status of the invoice in Stripe", "example": "draft" }, "stripe_invoice_id": { "type": [ "string", "null" ], "description": "The Stripe invoice ID" }, "description": { "type": [ "string", "null" ], "description": "A description of the invoice" }, "total": { "type": "number", "description": "The total amount of the invoice", "example": 99.99 }, "stripe_automatic_tax": { "type": [ "object", "null" ], "description": "Stripe automatic tax settings for this invoice", "properties": { "enabled": { "type": [ "boolean", "null" ], "description": "Whether Stripe automatic tax is enabled" } } } }, "additionalProperties": false, "required": [ "id", "charger_id", "charger_type", "chargee_id", "chargee_type", "created_at", "currency", "status", "stripe_invoice_status", "stripe_invoice_id", "description", "total", "stripe_automatic_tax" ] } }, "required": [ "message", "invoice" ] }, "examples": { "example": { "value": { "message": "Draft invoice created.", "invoice": { "id": 2, "charger_id": 1, "charger_type": "company", "chargee_id": 1, "chargee_type": "team", "created_at": "2023-08-09T16:39:26.558994Z", "currency": "USD", "status": "Draft", "stripe_invoice_status": null, "stripe_invoice_id": null, "description": null, "total": 293.8, "stripe_automatic_tax": { "enabled": null } } } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/billing/invoices/{invoice}/finalize": { "post": { "summary": "Finalize an invoice", "description": "Locks a draft invoice, preventing further modification to its charges. Once finalized, the invoice will be queued for creation on Stripe. This is a required step before attempting to collect payment.", "operationId": "finalize-invoice", "tags": [ "Billing" ], "parameters": [ { "name": "invoice", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the invoice to finalize", "example": 2 } } ], "responses": { "200": { "description": "The invoice was successfully finalized (or was already finalized)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invoice finalized and locked." } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Invoice finalized and locked." } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/billing/invoices/{invoice}/collect": { "post": { "summary": "Collect payment for an invoice", "description": "Triggers an immediate charge attempt against the merchant's credit card on file for a finalized invoice. The invoice must be finalized before collection can be attempted. If the invoice has not yet been created on Stripe, this endpoint will create and finalize it on Stripe before attempting collection.", "operationId": "collect-invoice", "tags": [ "Billing" ], "parameters": [ { "name": "invoice", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the invoice to collect payment for", "example": 2 } } ], "responses": { "200": { "description": "Payment collection was successfully initiated (or the invoice was already paid)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Payment collection initiated." } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Payment collection initiated." } } } } } }, "400": { "description": "The invoice has not been finalized and cannot be collected", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "This invoice has not been finalized" } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/inventory": { "get": { "summary": "List inventory items", "description": "Get a paginated list of inventory items for the current merchant or service provider.", "operationId": "get-inventory", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "A search query to filter items by title, SKU, identifier, tag, or condition", "example": "widget" } }, { "name": "ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "integer" }, "description": "Filter items by a list of item IDs" } }, { "name": "merchant_skus", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "description": "Filter items by a list of merchant SKUs" } }, { "name": "tag_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "integer" }, "description": "Filter items by a list of tag IDs" } }, { "name": "available_quantity_gt", "in": "query", "required": false, "schema": { "type": "integer", "description": "Filter items with available quantity greater than this value" } }, { "name": "available_quantity_lt", "in": "query", "required": false, "schema": { "type": "integer", "description": "Filter items with available quantity less than this value" } }, { "name": "quantity_in_stock_gt", "in": "query", "required": false, "schema": { "type": "integer", "description": "Filter items with quantity in stock greater than this value" } }, { "name": "quantity_in_stock_lt", "in": "query", "required": false, "schema": { "type": "integer", "description": "Filter items with quantity in stock less than this value" } }, { "name": "missing_dimensions_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, only return items missing dimension data" } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "description": "The field to sort results by" } }, { "name": "sort_dir", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "The sort direction" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "The page number to retrieve (1-indexed)", "example": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "The number of items per page", "example": 15 } } ], "responses": { "200": { "description": "A successful response returning the paginated list of inventory items", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "A paginated list of items using Conveyr's custom Page structure", "properties": { "data": { "type": "array", "description": "The list of items on the current page", "items": {} }, "total": { "type": "integer", "description": "The total number of items across all pages", "example": 42 }, "current_page": { "type": "integer", "description": "The current page number (1-indexed)", "example": 1 }, "last_page": { "type": "integer", "description": "The last page number", "example": 5 }, "per_page": { "type": "integer", "description": "The number of items per page", "example": 10 }, "from": { "type": [ "integer", "null" ], "description": "The 1-indexed position of the first item on the current page", "example": 1 }, "to": { "type": [ "integer", "null" ], "description": "The 1-indexed position of the last item on the current page", "example": 10 }, "first_page_url": { "type": "string", "description": "URL for the first page of results" }, "last_page_url": { "type": [ "string", "null" ], "description": "URL for the last page of results" }, "next_page_url": { "type": [ "string", "null" ], "description": "URL for the next page of results, or null if on the last page" }, "prev_page_url": { "type": [ "string", "null" ], "description": "URL for the previous page of results, or null if on the first page" }, "path": { "type": "string", "description": "Base URL path for pagination" }, "links": { "type": "array", "description": "Array of pagination link objects", "items": { "type": "object" } } }, "additionalProperties": false, "required": [ "data", "total", "current_page", "last_page", "per_page", "from", "to" ] }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/paths/~1inventory/post/responses/201/content/application~1json/schema/properties/data" } } }, "required": [ "data" ] } ] }, "examples": { "example": { "value": { "current_page": 1, "last_page": 1, "from": 1, "to": 1, "data": [ { "id": 96, "uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4", "created_at": "2022-04-01T09:34:55.000000Z", "updated_at": "2022-04-01T09:34:59.000000Z", "merchant_id": 2, "team_id": 2, "merchant_sku": "Synergist-163839", "title": "Synergistic Leather Shoes", "condition": "new", "condition_note": null, "are_dimensions_locked": false, "length_mm": 91, "width_mm": 286, "height_mm": 174, "weight_gm": 1076, "quantity_in_stock": 0, "fnsku": "X008VSER78", "asin": "B014IA92I8", "searchableIdentifiers": "B014IA92I8,X008VSER78,3495184061393", "images": [], "identifiers": [] } ], "per_page": 500, "total": 37 } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" } }, "tags": [ "Inventory" ] }, "post": { "summary": "Create an inventory item", "description": "Create a new inventory item for the current merchant.", "operationId": "create-inventory-item", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant_sku": { "type": "string", "description": "The merchant's own SKU for this item", "example": "WIDGET-001" }, "title": { "type": "string", "description": "The title or name of the item", "minLength": 3, "maxLength": 255, "example": "Blue Widget" }, "condition": { "type": [ "string", "null" ], "description": "The condition of the item", "example": "new" }, "condition_note": { "type": [ "string", "null" ], "description": "Additional notes about the condition", "example": "Minor cosmetic damage" }, "length_mm": { "type": [ "integer", "null" ], "description": "The length in millimetres", "minimum": 1, "maximum": 500000, "example": 150 }, "width_mm": { "type": [ "integer", "null" ], "description": "The width in millimetres", "minimum": 1, "maximum": 500000, "example": 100 }, "height_mm": { "type": [ "integer", "null" ], "description": "The height in millimetres", "minimum": 1, "maximum": 500000, "example": 50 }, "weight_gm": { "type": [ "integer", "null" ], "description": "The weight in grams", "minimum": 1, "maximum": 500000, "example": 500 } }, "required": [ "merchant_sku", "title" ] } } } }, "responses": { "201": { "description": "The inventory item was successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "InventoryItem", "type": "object", "description": "Representation of an inventory item", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the inventory item", "example": 1 }, "uuid": { "type": "string", "format": "uuid", "description": "The UUID of the inventory item", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the item was created", "example": "2024-01-15T12:00:00Z" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the item was last updated", "example": "2024-01-15T12:00:00Z" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the item was soft-deleted, or null if not deleted", "example": null }, "team_id": { "type": "integer", "description": "Alias for merchant_id", "example": 42 }, "merchant_id": { "type": "integer", "description": "The ID of the merchant that owns this item", "example": 42 }, "merchant_sku": { "type": "string", "description": "The merchant's own Stock Keeping Unit identifier", "example": "WIDGET-001" }, "title": { "type": "string", "description": "The title or name of the inventory item", "example": "Blue Widget" }, "condition": { "type": [ "string", "null" ], "description": "The condition of the item (e.g. new, used_like_new, used_good, used_acceptable)", "example": "new" }, "condition_note": { "type": [ "string", "null" ], "description": "Additional notes about the condition of the item", "example": "Minor cosmetic damage on the back panel" }, "length_mm": { "type": [ "integer", "null" ], "description": "The length of the item in millimetres", "example": 150 }, "width_mm": { "type": [ "integer", "null" ], "description": "The width of the item in millimetres", "example": 100 }, "height_mm": { "type": [ "integer", "null" ], "description": "The height of the item in millimetres", "example": 50 }, "weight_gm": { "type": [ "integer", "null" ], "description": "The weight of the item in grams", "example": 500 }, "are_dimensions_locked": { "type": [ "boolean", "null" ], "description": "Whether the item dimensions are locked and cannot be edited", "example": false }, "quantity_in_stock": { "type": [ "integer", "null" ], "description": "The total quantity of this item currently in stock across all locations" }, "available_quantity": { "type": [ "integer", "null" ], "description": "The quantity available for allocation (not yet allocated to orders)" }, "allocated_quantity": { "type": [ "integer", "null" ], "description": "The quantity currently allocated to open orders" }, "unavailable_quantity": { "type": [ "integer", "null" ], "description": "The quantity held in unavailable locations" }, "inbound_quantity": { "type": [ "integer", "null" ], "description": "The quantity expected from open inbound shipments" }, "searchableIdentifiers": { "type": "string", "description": "Comma-separated string of all identifier values for search (present when identifiers are loaded)" }, "fnsku": { "type": "string", "description": "The FNSKU identifier value (present when identifiers are loaded)" }, "asin": { "type": "string", "description": "The ASIN identifier value (present when identifiers are loaded)" }, "history": { "type": "array", "description": "Stock history entries for the item (only present on the detail endpoint)", "items": { "type": "object" } }, "images": { "type": "array", "description": "Array of images for the inventory item", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier of the image" }, "product_uuid": { "type": "string", "description": "The UUID of the inventory item this image belongs to" }, "large_url": { "type": [ "string", "null" ], "description": "URL for the large version of the image" }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL for the thumbnail version of the image" } }, "additionalProperties": false, "required": [ "id", "product_uuid" ] } }, "identifiers": { "type": "array", "description": "Array of item identifiers (ASIN, UPC, EAN, FNSKU, GTIN, CUSTOM)", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier of this identifier record" }, "product_uuid": { "type": "string", "description": "The UUID of the inventory item this identifier belongs to" }, "identifier": { "type": "string", "description": "The identifier value" }, "identifier_type": { "type": "string", "description": "The type of identifier", "enum": [ "ASIN", "EAN", "UPC", "FNSKU", "GTIN", "CUSTOM" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the identifier was created" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the identifier was last updated" } }, "additionalProperties": false, "required": [ "id", "product_uuid", "identifier", "identifier_type" ] } }, "tags": { "type": "array", "description": "Array of tags associated with the inventory item", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier of the tag" }, "name": { "type": "string", "description": "The name of the tag" } }, "additionalProperties": false, "required": [ "id", "name" ] } }, "production_formulas": { "type": "array", "description": "Production formulas associated with this item (only present on the detail endpoint)", "items": { "type": "object" } }, "item_group_configurations": { "type": "array", "description": "Item group configurations for this item (only present on the detail endpoint)", "items": { "type": "object" } }, "company_services": { "type": "array", "description": "Company services available for this item", "items": { "type": "object" } }, "stocks": { "type": "array", "description": "Stock records for this item across warehouse locations", "items": { "type": "object" } }, "traceability_groups": { "type": "array", "description": "Traceability groups for lot/expiry tracking (only present on the detail endpoint)", "items": { "type": "object" } } }, "additionalProperties": false, "required": [ "id", "uuid", "merchant_id", "team_id", "merchant_sku", "title", "are_dimensions_locked" ] } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "id": 2362, "uuid": "2f8b1c3e-d4a5-4e6f-b7c8-e9d0f1a2b3c4", "created_at": "2025-03-12T09:42:40Z", "updated_at": "2025-03-12T09:42:40Z", "merchant_id": 2, "team_id": 2, "merchant_sku": "0D-O2GN-CNH9", "title": "Test", "condition": null, "condition_note": null, "are_dimensions_locked": null } } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "description": "Unprocessable Entity — the request body failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A summary of the validation error", "example": "The given data was invalid." }, "errors": { "type": "object", "description": "A map of field names to arrays of error messages", "example": { "name": [ "The name field is required." ] } } }, "required": [ "message", "errors" ] } } } } }, "tags": [ "Inventory" ] } }, "/inventory/search": { "post": { "summary": "Search inventory items", "description": "Search for inventory items using a text query and optional filters.", "operationId": "search-inventory", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "The search query string", "example": "blue widget" }, "mode": { "type": [ "string", "null" ], "description": "The search mode to use. Defaults to 'default'.", "enum": [ "default", "title_similarity" ], "example": "default" }, "filters": { "type": [ "object", "null" ], "description": "Optional filters to apply to the search", "properties": { "condition_type": { "type": [ "string", "null" ], "description": "Filter by condition type (e.g. new, used)", "example": "new" } } } }, "required": [ "q" ] } } } }, "responses": { "200": { "description": "A successful response returning matching inventory items", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/paths/~1inventory/post/responses/201/content/application~1json/schema/properties/data" } } }, "required": [ "items" ] }, "examples": { "example": { "value": { "items": [ { "id": 9, "uuid": "3a9c2d4e-f5b6-4c7d-a8e9-f0a1b2c3d4e5", "created_at": "2021-02-19T14:11:38.000000Z", "updated_at": "2021-02-19T14:11:38.000000Z", "merchant_id": 2, "team_id": 2, "merchant_sku": "Heavy-Duty-979091", "title": "Heavy Duty Wool Keyboard", "condition": null, "condition_note": null, "are_dimensions_locked": false, "length_mm": 589, "width_mm": 212, "height_mm": 509, "weight_gm": 3602, "fnsku": "X00U2E5ZYE", "asin": "B07611F2KY", "images": [], "identifiers": [], "company_services": [] } ] } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } }, "tags": [ "Inventory" ] } }, "/inventory/{item}": { "get": { "summary": "Show an inventory item", "description": "Get a single inventory item by its ID.", "operationId": "get-inventory-item", "parameters": [ { "name": "item", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the inventory item", "example": 1 } } ], "responses": { "200": { "description": "A successful response returning the inventory item", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/paths/~1inventory/post/responses/201/content/application~1json/schema/properties/data" } }, "required": [ "item" ] }, "examples": { "example": { "value": { "item": { "id": 50, "uuid": "4b0d3e5f-a6c7-4d8e-b9f0-a1b2c3d4e5f6", "created_at": "2024-04-15T08:23:47.000000Z", "updated_at": "2024-04-15T08:23:47.000000Z", "deleted_at": null, "merchant_id": 2, "team_id": 2, "merchant_sku": "Recycled-Pa-443089", "title": "Recycled Paper Notebooks", "condition": "new", "condition_note": null, "are_dimensions_locked": false, "length_mm": 68, "width_mm": 140, "height_mm": 120, "weight_gm": 540, "quantity_in_stock": 0, "available_quantity": 0, "allocated_quantity": 0, "unavailable_quantity": 0, "inbound_quantity": 0, "history": [], "images": [], "identifiers": [], "tags": [], "production_formulas": [], "item_group_configurations": [], "company_services": [], "stocks": [], "traceability_groups": [] } } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" } }, "tags": [ "Inventory" ] }, "put": { "summary": "Update an inventory item", "description": "Update an existing inventory item.", "operationId": "update-inventory-item", "parameters": [ { "name": "item", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the inventory item", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "description": "The title or name of the item", "minLength": 3, "maxLength": 255, "example": "Blue Widget" }, "condition": { "type": [ "string", "null" ], "description": "The condition of the item", "example": "new" }, "condition_note": { "type": [ "string", "null" ], "description": "Additional notes about the condition", "example": "Minor cosmetic damage" }, "length_mm": { "type": [ "integer", "null" ], "description": "The length in millimetres", "minimum": 1, "maximum": 500000, "example": 150 }, "width_mm": { "type": [ "integer", "null" ], "description": "The width in millimetres", "minimum": 1, "maximum": 500000, "example": 100 }, "height_mm": { "type": [ "integer", "null" ], "description": "The height in millimetres", "minimum": 1, "maximum": 500000, "example": 50 }, "weight_gm": { "type": [ "integer", "null" ], "description": "The weight in grams", "minimum": 1, "maximum": 500000, "example": 500 } } } } } }, "responses": { "200": { "description": "The inventory item was successfully updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A success message", "example": "Item updated" }, "item": { "$ref": "#/paths/~1inventory/post/responses/201/content/application~1json/schema/properties/data" } }, "required": [ "message", "item" ] }, "examples": { "example": { "value": { "message": "Item updated", "item": { "id": 151, "created_at": "2024-04-03T11:19:35.000000Z", "updated_at": "2024-04-03T11:19:35.000000Z", "merchant_id": 2, "merchant_sku": "3J-NO51-ICT7", "title": "Test Title", "condition": "new", "condition_note": null, "length_mm": 140, "width_mm": 140, "height_mm": 140, "weight_gm": 240, "fnsku": "", "asin": "", "searchableIdentifiers": "", "images": [], "identifiers": [] } } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } }, "tags": [ "Inventory" ] } }, "/inventory/{item}/identifier": { "post": { "summary": "Add an identifier to an inventory item", "description": "Add a new identifier (ASIN, EAN, UPC, FNSKU, GTIN, or CUSTOM) to an inventory item.", "operationId": "add-inventory-item-identifier", "parameters": [ { "name": "item", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the inventory item", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier_type": { "type": "string", "description": "The type of identifier to add", "enum": [ "ASIN", "EAN", "UPC", "FNSKU", "GTIN", "CUSTOM" ], "example": "ASIN" }, "identifier": { "type": "string", "description": "The identifier value", "maxLength": 255, "example": "B0001234AB" } }, "required": [ "identifier_type", "identifier" ] } } } }, "responses": { "200": { "description": "The identifier was successfully added", "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier of this identifier record" }, "identifier": { "type": "string", "description": "The identifier value" }, "identifier_type": { "type": "string", "description": "The type of identifier", "enum": [ "ASIN", "EAN", "UPC", "FNSKU", "GTIN", "CUSTOM" ] } }, "required": [ "id", "identifier", "identifier_type" ] } }, "required": [ "identifier" ] }, "examples": { "example": { "value": { "identifier": { "id": 1, "identifier": "B0001234AB", "identifier_type": "ASIN" } } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } }, "tags": [ "Inventory" ] } }, "/inventory/services": { "post": { "summary": "Manage services for an inventory item", "description": "Sync the company services associated with an inventory item.", "operationId": "manage-inventory-item-services", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "item_id": { "type": "integer", "description": "The ID of the inventory item", "example": 1 }, "services": { "type": "array", "description": "The list of company service IDs to associate with the item", "items": { "type": "integer", "description": "A company service ID" }, "example": [ 1, 2, 3 ] } }, "required": [ "item_id", "services" ] } } } }, "responses": { "200": { "description": "The services were successfully synced", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A success message", "example": "Services updated" } } }, "examples": { "example": { "value": { "message": "Services Updated" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } }, "tags": [ "Inventory" ] } }, "/shipments/inbound": { "get": { "summary": "List inbound shipments", "description": "Get a paginated list of active (non-archived) inbound shipments.", "operationId": "get-inbound-shipments", "parameters": [ { "name": "filters[not_received]", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, only return shipments that have not yet been received" } }, { "name": "page", "in": "query", "required": false, "schema": { "$ref": "#/paths/~1inventory/get/parameters/11/schema" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "$ref": "#/paths/~1inventory/get/parameters/12/schema" } } ], "responses": { "200": { "description": "A successful response returning the paginated list of inbound shipments", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/paths/~1inventory/get/responses/200/content/application~1json/schema/allOf/0" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/paths/~1shipments~1inbound~1%7Binbound_shipment%7D/put/responses/200/content/application~1json/schema/properties/shipment" } } }, "required": [ "data" ] } ] }, "examples": { "example": { "value": { "current_page": 1, "data": [ { "id": 39, "created_at": "2022-03-26T10:23:55.000000Z", "updated_at": "2022-03-28T12:52:00.000000Z", "merchant_id": 2, "team_id": 2, "name": "Crooks, Reilly and Predovic", "notes": "Ipsam et quaerat voluptates iure quae.", "status": "shipped", "warehouse_id": 1, "received_at": null, "internal_notes": null, "archived_at": null, "expected_quantity": 680, "sku_count": 7, "actual_quantity": 0, "unsellable_quantity": 4, "received_quantity": 4, "reference_id": "INSH-032622-39", "searchable_identifiers": "B01N1KM25E,X00FK2YTUF,0751765057210" } ], "from": 1, "last_page": 2, "per_page": 20, "to": 20, "total": 30 } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" } }, "tags": [ "Inbound Shipments" ] }, "post": { "summary": "Create an inbound shipment", "description": "Create a new inbound shipment for the current merchant.", "operationId": "create-inbound-shipment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the shipment", "minLength": 3, "maxLength": 255, "example": "January Restock 2024" }, "warehouse_id": { "type": "integer", "description": "The ID of the destination warehouse", "example": 5 }, "notes": { "type": [ "string", "null" ], "description": "Optional notes about the shipment", "example": "Handle with care" } }, "required": [ "name", "warehouse_id" ] } } } }, "responses": { "201": { "description": "The inbound shipment was successfully created", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A success message", "example": "Shipment created" }, "shipment_id": { "type": "integer", "description": "The ID of the newly created shipment", "example": 1001 } }, "required": [ "message", "shipment_id" ] }, "examples": { "example": { "value": { "message": "Shipment created", "shipment_id": 22 } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } }, "tags": [ "Inbound Shipments" ] } }, "/shipments/inbound/archived": { "get": { "summary": "List archived inbound shipments", "description": "Get a paginated list of archived inbound shipments.", "operationId": "get-archived-inbound-shipments", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "$ref": "#/paths/~1inventory/get/parameters/11/schema" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "$ref": "#/paths/~1inventory/get/parameters/12/schema" } } ], "responses": { "200": { "description": "A successful response returning the paginated list of archived inbound shipments", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/paths/~1inventory/get/responses/200/content/application~1json/schema/allOf/0" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/paths/~1shipments~1inbound~1%7Binbound_shipment%7D/put/responses/200/content/application~1json/schema/properties/shipment" } } }, "required": [ "data" ] } ] } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" } }, "tags": [ "Inbound Shipments" ] } }, "/shipments/inbound/{inbound_shipment}": { "get": { "summary": "Show an inbound shipment", "description": "Get a single inbound shipment by its ID, including attachments, service lines, warehouse, and tags.", "operationId": "get-inbound-shipment", "parameters": [ { "name": "inbound_shipment", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the inbound shipment", "example": 1001 } } ], "responses": { "200": { "description": "A successful response returning the inbound shipment", "content": { "application/json": { "schema": { "type": "object", "properties": { "shipment": { "allOf": [ { "$ref": "#/paths/~1shipments~1inbound~1%7Binbound_shipment%7D/put/responses/200/content/application~1json/schema/properties/shipment" }, { "type": "object", "properties": { "attachments": { "type": "array", "description": "File attachments on the shipment", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" }, "path": { "type": "string" } }, "required": [ "id", "name", "url", "path" ] } }, "service_lines": { "type": "array", "description": "Service lines for billing purposes", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "quantity": { "type": "integer" }, "service": { "type": [ "object", "null" ] } }, "required": [ "id", "quantity", "service" ] } }, "warehouse": { "type": [ "object", "null" ], "description": "The destination warehouse", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "tracking_numbers": { "type": "array", "description": "Tracking numbers associated with the shipment", "items": { "type": "object" } } } } ] } }, "required": [ "shipment" ] }, "examples": { "example": { "value": { "shipment": { "id": 19, "created_at": "2024-01-26T14:51:01.000000Z", "updated_at": "2024-01-29T07:18:52.000000Z", "merchant_id": 1, "team_id": 1, "name": "Binary Burst 12", "notes": "Validate shipment contents against packing list to ensure accuracy.", "warehouse_id": 1, "received_at": null, "internal_notes": null, "archived_at": null, "shipped_at": "2024-01-26T14:51:01.000000Z", "checked_in_at": null, "deleted_at": null, "currency": "USD", "eta": "2024-01-23T09:51:01Z", "expected_quantity": 310, "sku_count": 5, "shipment_id": null, "actual_quantity": 0, "unsellable_quantity": 0, "received_quantity": 0, "reference_id": "INSH-012624-19", "status": "shipped", "tracking_numbers": [], "attachments": [], "service_lines": [], "warehouse": { "id": 1, "uuid": "0197e188-5d70-8010-bf60-252ed9687632", "name": "NY Warehouse" }, "tags": [] } } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" } }, "tags": [ "Inbound Shipments" ] }, "put": { "summary": "Update an inbound shipment", "description": "Update an existing inbound shipment.", "operationId": "update-inbound-shipment", "parameters": [ { "name": "inbound_shipment", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the inbound shipment", "example": 1001 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "The name of the shipment", "minLength": 3, "maxLength": 255, "example": "January Restock 2024 (Updated)" }, "notes": { "type": [ "string", "null" ], "description": "Notes about the shipment", "example": "Handle with care" }, "internal_notes": { "type": [ "string", "null" ], "description": "Internal notes visible only to staff", "example": "Priority processing requested" }, "eta": { "type": [ "string", "null" ], "format": "date-time", "description": "The estimated time of arrival", "example": "2024-01-24T00:00:00Z" } } } } } }, "responses": { "200": { "description": "The inbound shipment was successfully updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "shipment": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "InboundShipment", "type": "object", "description": "Representation of an inbound shipment", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the inbound shipment", "example": 1001 }, "uuid": { "type": "string", "format": "uuid", "description": "The UUID of the inbound shipment", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the shipment was created", "example": "2024-01-15T12:00:00Z" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the shipment was last updated", "example": "2024-01-15T12:00:00Z" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the shipment was soft-deleted, or null if not deleted" }, "checked_in_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the shipment was checked in at the warehouse" }, "name": { "type": "string", "description": "The name of the inbound shipment", "minLength": 3, "maxLength": 255, "example": "January Restock 2024" }, "notes": { "type": [ "string", "null" ], "description": "Notes about the shipment", "example": "Handle with care" }, "internal_notes": { "type": [ "string", "null" ], "description": "Internal notes visible only to service provider staff", "example": "Customer requested priority processing" }, "merchant_id": { "type": "integer", "description": "The ID of the merchant that owns this shipment", "example": 42 }, "team_id": { "type": "integer", "description": "Alias for merchant_id", "example": 42 }, "warehouse_id": { "type": "integer", "description": "The ID of the destination warehouse", "example": 5 }, "reference_id": { "type": [ "string", "null" ], "description": "A human-readable reference identifier for the shipment", "example": "INSH-011524-1001" }, "status": { "type": "string", "description": "The current status of the shipment", "enum": [ "open", "shipped", "received" ], "example": "open" }, "shipped_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the shipment was marked as shipped", "example": "2024-01-20T10:00:00Z" }, "received_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the shipment was received at the warehouse", "example": "2024-01-25T14:30:00Z" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the shipment was archived", "example": null }, "eta": { "type": [ "string", "null" ], "format": "date-time", "description": "The estimated time of arrival", "example": "2024-01-24T00:00:00Z" }, "currency": { "type": [ "string", "null" ], "description": "The currency code for billing purposes", "example": "USD" }, "migrated": { "type": [ "boolean", "null" ], "description": "Whether this shipment has been migrated from a legacy system" }, "sku_count": { "type": [ "integer", "null" ], "description": "The number of distinct SKUs in the shipment" }, "expected_quantity": { "type": [ "integer", "null" ], "description": "The total expected quantity of items across all SKUs" }, "actual_quantity": { "type": [ "integer", "null" ], "description": "The total actually received quantity across all SKUs" }, "unsellable_quantity": { "type": [ "integer", "null" ], "description": "The total quantity received in unsellable condition" }, "received_quantity": { "type": [ "integer", "null" ], "description": "The total quantity received so far" }, "searchable_identifiers": { "type": [ "string", "null" ], "description": "Comma-separated string of item identifier values for search (list endpoint only)" }, "searchable_tags": { "type": [ "array", "null" ], "description": "Tag names for search (list endpoint only)", "items": { "type": "string" } }, "tags": { "type": "array", "description": "Tags associated with the shipment", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier of the tag" }, "name": { "type": "string", "description": "The name of the tag" } }, "additionalProperties": false, "required": [ "id", "name" ] } }, "attachments": { "type": "array", "description": "File attachments on the shipment (only present on the detail endpoint)", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" }, "path": { "type": "string" } }, "additionalProperties": false, "required": [ "id", "name", "url", "path" ] } }, "service_lines": { "type": "array", "description": "Service lines for billing purposes (only present on the detail endpoint)", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "quantity": { "type": "integer" }, "service": { "type": [ "object", "null" ] } }, "additionalProperties": false, "required": [ "id", "quantity", "service" ] } }, "warehouse": { "type": [ "object", "null" ], "description": "The destination warehouse (only present on the detail endpoint)" }, "tracking_numbers": { "type": "array", "description": "Tracking numbers associated with the shipment (only present on the detail endpoint)", "items": { "type": "object" } }, "shipment_id": { "type": [ "string", "null" ], "description": "External shipment ID reference" } }, "additionalProperties": false, "required": [ "id", "name", "merchant_id", "team_id", "warehouse_id", "status" ] } }, "required": [ "shipment" ] }, "examples": { "example": { "value": { "shipment": { "id": 46, "created_at": "2021-10-19T07:48:05.000000Z", "updated_at": "2021-10-26T17:29:18.000000Z", "merchant_id": 2, "name": "Lindgren-Cormier", "notes": "Inventore iusto facilis aperiam modi est.", "status": "shipped", "warehouse_id": 1, "received_at": null, "internal_notes": null } } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } }, "tags": [ "Inbound Shipments" ] } }, "/shipments/inbound/{inbound_shipment}/submit": { "post": { "summary": "Submit an inbound shipment", "description": "Mark an inbound shipment as shipped. Optionally include a carrier and tracking numbers.", "operationId": "submit-inbound-shipment", "parameters": [ { "name": "inbound_shipment", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the inbound shipment", "example": 1001 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "carrier": { "type": [ "string", "null" ], "description": "The carrier used for shipping", "example": "ups" }, "tracking_numbers": { "type": "array", "description": "List of tracking numbers. Required when carrier is provided.", "items": { "type": "string", "description": "A tracking number", "example": "1Z999AA10123456784" } } } } } } }, "responses": { "200": { "description": "The shipment was successfully submitted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A success message", "example": "Shipment submitted" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Shipment submitted" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } }, "tags": [ "Inbound Shipments" ] } }, "/shipments/inbound/{inbound_shipment}/receive": { "post": { "summary": "Receive an inbound shipment", "description": "Mark an inbound shipment as received at the warehouse.", "operationId": "receive-inbound-shipment", "parameters": [ { "name": "inbound_shipment", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the inbound shipment", "example": 1001 } } ], "responses": { "200": { "description": "The shipment was successfully received", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A success message", "example": "Shipment received" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Shipment received" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" } }, "tags": [ "Inbound Shipments" ] } }, "/shipments/inbound/batch/archive": { "post": { "summary": "Batch archive inbound shipments", "description": "Archive multiple inbound shipments at once.", "operationId": "batch-archive-inbound-shipments", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shipment_ids": { "type": "array", "description": "The IDs of the shipments to archive", "minItems": 1, "items": { "type": "integer", "description": "An inbound shipment ID", "example": 1001 } } }, "required": [ "shipment_ids" ] } } } }, "responses": { "200": { "description": "The shipments were successfully archived", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A success message", "example": "Shipments archived" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Shipments archived" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } }, "tags": [ "Inbound Shipments" ] } }, "/shipments/inbound/{inbound_shipment}/items": { "get": { "summary": "List items for an inbound shipment", "description": "Get the list of items (expected, actual, and unsellable) for an inbound shipment.", "operationId": "get-inbound-shipment-items", "parameters": [ { "name": "inbound_shipment", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the inbound shipment", "example": 1001 } }, { "name": "item_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "integer" }, "description": "Filter to a specific list of item IDs" } } ], "responses": { "200": { "description": "A successful response returning the shipment items", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of shipment items with expected, actual, and unsellable quantities", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The item ID" }, "item_id": { "type": "integer", "description": "The inventory item ID" }, "shipment_id": { "type": "integer", "description": "The inbound shipment ID" }, "item": { "type": "object", "description": "The inventory item details" }, "expected": { "type": "object", "description": "Expected quantity information", "properties": { "id": { "type": [ "integer", "null" ] }, "quantity": { "type": "integer" }, "item_group_configurations": { "type": "array", "items": { "type": "object" } } }, "required": [ "quantity", "item_group_configurations" ] }, "actual": { "type": "object", "description": "Actual received quantity information", "properties": { "id": { "type": [ "integer", "null" ] }, "quantity": { "type": "integer" }, "item_group_configurations": { "type": "array", "items": { "type": "object" } }, "moves": { "type": "array", "items": { "type": "object" } } }, "required": [ "quantity", "item_group_configurations", "moves" ] }, "unsellable": { "type": "object", "description": "Unsellable quantity information", "properties": { "id": { "type": [ "integer", "null" ] }, "quantity": { "type": "integer" } }, "required": [ "quantity" ] } }, "required": [ "item_id", "shipment_id", "expected", "actual", "unsellable" ] } } }, "required": [ "items" ] }, "examples": { "example": { "value": { "items": [ { "id": 1, "item_id": 1, "shipment_id": 629, "expected": { "quantity": 10, "item_group_configurations": [], "id": 1072 }, "actual": { "quantity": 10, "item_group_configurations": [], "moves": [], "id": 830 }, "unsellable": { "quantity": 0 }, "item": { "id": 1, "merchant_sku": "Silicone-223984", "title": "1 - Silicone Baking Mats", "condition": "new" } } ] } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" } }, "tags": [ "Inbound Shipments" ] } }, "/shipments/inbound/{inbound_shipment}/add-item": { "post": { "summary": "Add an item to an inbound shipment", "description": "Add an inventory item with a specified quantity to an inbound shipment.", "operationId": "add-item-to-inbound-shipment", "parameters": [ { "name": "inbound_shipment", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the inbound shipment", "example": 1001 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "item_id": { "type": "integer", "description": "The ID of the inventory item to add", "example": 42 }, "quantity": { "type": "integer", "description": "The expected quantity of the item", "minimum": 1, "example": 10 } }, "required": [ "item_id", "quantity" ] } } } }, "responses": { "200": { "description": "The item was successfully added to the shipment", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A success message", "example": "Item added to shipment" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Item added to shipment" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } }, "tags": [ "Inbound Shipments" ] } }, "/shipments/inbound/{inbound_shipment}/update-item": { "post": { "summary": "Update an item on an inbound shipment", "description": "Update the expected and actual quantities for an item on an inbound shipment.", "operationId": "update-item-on-inbound-shipment", "parameters": [ { "name": "inbound_shipment", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the inbound shipment", "example": 1001 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "item_id": { "type": "integer", "description": "The ID of the inventory item to update", "example": 42 }, "expected": { "type": "object", "description": "Expected quantity update", "properties": { "quantity": { "type": "integer", "description": "The new expected quantity", "example": 10 }, "item_group_configurations": { "type": "array", "description": "Group configuration summaries", "items": { "type": "object", "properties": { "configuration_id": { "type": "integer" }, "quantity": { "type": "integer" }, "partial_quantity": { "type": "integer" } } } } }, "required": [ "quantity" ] }, "actual": { "type": "object", "description": "Actual quantity update (only available to service provider staff)", "properties": { "quantity": { "type": "integer", "description": "The new actual received quantity", "example": 8 }, "item_group_configurations": { "type": "array", "description": "Group configuration summaries", "items": { "type": "object", "properties": { "configuration_id": { "type": "integer" }, "quantity": { "type": "integer" }, "partial_quantity": { "type": "integer" } } } }, "moves": { "type": "array", "description": "Stock move data", "items": { "type": "object" } } }, "required": [ "quantity" ] } }, "required": [ "item_id", "expected" ] } } } }, "responses": { "200": { "description": "The item was successfully updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A success message", "example": "Item updated" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Item updated" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } }, "tags": [ "Inbound Shipments" ] } }, "/shipments/inbound/{inbound_shipment}/remove-item": { "post": { "summary": "Remove an item from an inbound shipment", "description": "Remove an inventory item from an inbound shipment.", "operationId": "remove-item-from-inbound-shipment", "parameters": [ { "name": "inbound_shipment", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the inbound shipment", "example": 1001 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "item_id": { "type": "integer", "description": "The ID of the inventory item to remove", "example": 42 } }, "required": [ "item_id" ] } } } }, "responses": { "200": { "description": "The item was successfully removed from the shipment", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A success message", "example": "Item removed from shipment" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Item removed from shipment" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } }, "tags": [ "Inbound Shipments" ] } }, "/shipments/outbound": { "get": { "summary": "List outbound shipments", "operationId": "list-outbound-shipments", "tags": [ "Outbound Shipments" ], "parameters": [ { "name": "filters[not_shipped]", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Filter to only return shipments that have not been shipped" } } ], "responses": { "200": { "description": "A successful response returning the paginated list of outbound shipments", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/paths/~1inventory/get/responses/200/content/application~1json/schema/allOf/0" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/paths/~1shipments~1outbound~1%7Boutbound_shipment%7D/get/responses/200/content/application~1json/schema/properties/shipment/allOf/0" }, { "type": "object", "properties": { "sku_count": { "type": [ "integer", "null" ], "description": "The number of distinct SKUs in this shipment" }, "shipped_items_count": { "type": [ "integer", "null" ], "description": "The number of items that have been shipped" }, "searchable_identifiers": { "type": [ "string", "null" ], "description": "A comma-separated string of searchable identifiers for this shipment" }, "searchable_tags": { "type": "array", "description": "Array of searchable tags for this shipment", "items": { "type": "string" } }, "fba_transport_v2024_plans": { "type": "array", "description": "FBA transport v2024 plans associated with this shipment", "items": { "type": "object", "properties": { "outbound_shipment_id": { "type": "string", "description": "The outbound shipment ID" }, "name": { "type": [ "string", "null" ], "description": "The name of the plan" }, "inbound_plan_id": { "type": [ "string", "null" ], "description": "The Amazon inbound plan ID" }, "fba_transport_v2024_plan_id": { "type": "string", "description": "The FBA transport v2024 plan ID" }, "status": { "type": [ "string", "null" ], "description": "The status of the plan" }, "total_quantity": { "type": [ "string", "null" ], "description": "The total quantity of items in the plan" }, "distinct_sku_count": { "type": [ "string", "null" ], "description": "The number of distinct SKUs in the plan" } }, "required": [ "outbound_shipment_id", "fba_transport_v2024_plan_id" ] } } } } ] } } }, "required": [ "data" ] } ] }, "examples": { "example": { "value": { "current_page": 1, "last_page": 2, "from": 1, "to": 20, "data": [ { "id": 5657, "created_at": "2024-07-24T11:09:48.000000Z", "updated_at": "2024-07-24T11:13:07.000000Z", "merchant_id": 1, "status": "open", "notes": null, "name": "Test Plans", "warehouse_id": 1, "shipped_at": null, "internal_notes": null, "archived_at": null, "currency": "USD", "is_case_forwarding": false, "sku_count": 1, "shipped_items_count": 5, "searchable_identifiers": "B00LIRROR6,X00N2VJGHH", "searchable_tags": [], "tags": [], "fba_transport_plans": [] } ], "per_page": 20, "total": 22 } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" } } }, "post": { "summary": "Create an outbound shipment", "operationId": "create-outbound-shipment", "tags": [ "Outbound Shipments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the outbound shipment", "minLength": 3, "maxLength": 255, "example": "My FBA Shipment" }, "notes": { "type": [ "string", "null" ], "description": "Optional notes for the outbound shipment" }, "warehouse_id": { "type": "integer", "description": "The ID of the warehouse for this shipment", "example": 1 } }, "required": [ "name", "warehouse_id" ] } } } }, "responses": { "200": { "description": "A successful response after creating the outbound shipment", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Shipment Created" }, "shipment_id": { "type": "integer", "description": "The ID of the newly created shipment", "example": 1 } }, "required": [ "message", "shipment_id" ] }, "examples": { "example": { "value": { "message": "Shipment Created", "shipment_id": 22 } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/shipments/outbound/archived": { "get": { "summary": "List archived outbound shipments", "operationId": "list-archived-outbound-shipments", "tags": [ "Outbound Shipments" ], "responses": { "200": { "description": "A successful response returning the paginated list of archived outbound shipments", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/paths/~1inventory/get/responses/200/content/application~1json/schema/allOf/0" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/paths/~1shipments~1outbound~1%7Boutbound_shipment%7D/get/responses/200/content/application~1json/schema/properties/shipment/allOf/0" }, { "type": "object", "properties": { "sku_count": { "type": [ "integer", "null" ], "description": "The number of distinct SKUs in this shipment" }, "shipped_items_count": { "type": [ "integer", "null" ], "description": "The number of items that have been shipped" }, "searchable_identifiers": { "type": [ "string", "null" ], "description": "A comma-separated string of searchable identifiers for this shipment" }, "searchable_tags": { "type": "array", "description": "Array of searchable tags for this shipment", "items": { "type": "string" } }, "fba_transport_v2024_plans": { "type": "array", "description": "FBA transport v2024 plans associated with this shipment", "items": { "type": "object" } } } } ] } } }, "required": [ "data" ] } ] } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" } } } }, "/shipments/outbound/{outbound_shipment}": { "get": { "summary": "Get an outbound shipment", "operationId": "get-outbound-shipment", "tags": [ "Outbound Shipments" ], "parameters": [ { "name": "outbound_shipment", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the outbound shipment", "example": 1 } } ], "responses": { "200": { "description": "A successful response returning the outbound shipment with its relations", "content": { "application/json": { "schema": { "type": "object", "properties": { "shipment": { "allOf": [ { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier for the outbound shipment", "example": 1 }, "uuid": { "type": [ "string", "null" ], "description": "The UUID of the outbound shipment" }, "name": { "type": "string", "description": "The name of the outbound shipment", "example": "My FBA Shipment" }, "notes": { "type": [ "string", "null" ], "description": "Notes for the outbound shipment" }, "internal_notes": { "type": [ "string", "null" ], "description": "Internal notes for the outbound shipment" }, "status": { "type": "string", "description": "The current status of the outbound shipment", "example": "open" }, "merchant_id": { "type": "integer", "description": "The ID of the merchant this shipment belongs to", "example": 1 }, "team_id": { "type": "integer", "description": "Alias for merchant_id" }, "warehouse_id": { "type": "integer", "description": "The ID of the warehouse for this shipment", "example": 1 }, "warehouse_uuid": { "type": [ "string", "null" ], "description": "The UUID of the warehouse for this shipment" }, "customer_id": { "type": [ "integer", "null" ], "description": "The ID of the customer associated with this shipment" }, "channel_id": { "type": [ "integer", "null" ], "description": "The ID of the channel associated with this shipment" }, "ship_from_address_id": { "type": [ "integer", "null" ], "description": "The ID of the address this shipment is shipped from" }, "shipped_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the shipment was shipped", "example": "2024-01-01T00:00:00Z" }, "archived_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the shipment was archived" }, "priced_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the shipment was priced" }, "cancellation_requested_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when cancellation was requested" }, "cancellation_request_reason": { "type": [ "string", "null" ], "description": "The reason provided for the cancellation request" }, "cancellation_denied_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the cancellation was denied" }, "cancellation_denial_reason": { "type": [ "string", "null" ], "description": "The reason the cancellation was denied" }, "is_case_forwarding": { "type": "boolean", "description": "Whether the shipment is a case forwarding shipment" }, "is_locked": { "type": [ "boolean", "null" ], "description": "Whether the shipment is locked" }, "currency": { "type": [ "string", "null" ], "description": "The ISO 4217 currency code for the shipment", "example": "USD" }, "sku_count": { "type": [ "integer", "null" ], "description": "The number of distinct SKUs in the shipment (list endpoint only)" }, "shipped_items_count": { "type": [ "integer", "null" ], "description": "The total number of items shipped (list endpoint only)" }, "pallets": { "type": [ "array", "null" ], "description": "Pallets associated with this shipment", "items": { "type": "object" } }, "errors": { "type": [ "array", "null" ], "description": "Errors associated with this shipment", "items": { "type": "object" } }, "marketplace_data": { "description": "Marketplace-specific data for this shipment" }, "searchable_identifiers": { "type": [ "string", "null" ], "description": "Comma-separated string of item identifier values for search (list endpoint only)" }, "searchable_tags": { "type": [ "array", "null" ], "description": "Tag names for search (list endpoint only)", "items": { "type": "string" } }, "tags": { "type": "array", "description": "Tags associated with the shipment", "items": { "type": "object" } }, "fba_transport_v2024_plans": { "type": "array", "description": "FBA transport v2024 plans linked to this shipment (list endpoint only)", "items": { "type": "object" } }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the shipment was created", "example": "2024-01-01T00:00:00Z" }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the shipment was last updated", "example": "2024-01-01T00:00:00Z" }, "warehouse": { "type": [ "object", "null" ], "description": "The warehouse details (detail endpoint only)" }, "outbound_items": { "type": "array", "description": "Items in the outbound shipment (detail endpoint only)", "items": { "type": "object" } }, "service_lines": { "type": "array", "description": "Service lines for billing (detail endpoint only)", "items": { "type": "object" } }, "attachments": { "type": "array", "description": "File attachments (detail endpoint only)", "items": { "type": "object" } }, "is_case_packed": { "type": [ "boolean", "null" ], "description": "Whether the shipment uses case-packed items" }, "fba_transport_plans": { "type": "array", "description": "FBA transport plans linked to this shipment", "items": { "type": "object" } } }, "additionalProperties": false, "required": [ "id", "name", "status", "merchant_id", "warehouse_id", "is_case_forwarding", "created_at", "updated_at" ] }, { "type": "object", "properties": { "outbound_items": { "type": "array", "description": "The items in this shipment", "items": { "type": "object" } }, "service_lines": { "type": "array", "description": "The service lines for this shipment", "items": { "type": "object" } }, "attachments": { "type": "array", "description": "The attachments for this shipment", "items": { "type": "object" } }, "tags": { "type": "array", "description": "The tags for this shipment", "items": { "type": "object" } }, "warehouse": { "type": [ "object", "null" ], "description": "The warehouse for this shipment" } } } ] } }, "required": [ "shipment" ] }, "examples": { "example": { "value": { "shipment": { "id": 6, "created_at": "2024-07-23T06:51:11.000000Z", "updated_at": "2024-06-04T12:45:12.000000Z", "merchant_id": 1, "status": "closed", "notes": null, "name": "Triton Tech", "warehouse_id": 1, "shipped_at": "2024-07-23T06:51:11.000000Z", "internal_notes": null, "errors": null, "ship_from_address_id": null, "archived_at": null, "currency": "USD", "is_case_forwarding": false, "is_case_packed": true, "outbound_items": [ { "id": 14, "shipment_id": 6, "item_id": 21, "quantity": 20, "case_quantity": null, "expiry_date": null, "item": { "id": 21, "merchant_sku": "Crystal-W-283235", "title": "Crystal Wine Decanter", "fnsku": "X007V73BAF", "asin": "B04Z6GUVL5" } } ], "service_lines": [], "attachments": [], "tags": [] } } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" } } } }, "/shipments/outbound/{outbound_shipment}/attachment": { "post": { "summary": "Upload an attachment to an outbound shipment", "operationId": "upload-outbound-shipment-attachment", "tags": [ "Outbound Shipments" ], "parameters": [ { "name": "outbound_shipment", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the outbound shipment", "example": 1 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "A single file to upload as an attachment" }, "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Multiple files to upload as attachments" }, "name": { "type": "string", "description": "The name of the attachment (used when uploading a single file)" } } } } } }, "responses": { "200": { "description": "A successful response after uploading the attachment", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Attachments have been uploaded to this shipment." }, "attachments": { "type": "array", "description": "The uploaded attachments", "items": { "type": "object" } } }, "required": [ "message", "attachments" ] }, "examples": { "example": { "value": { "message": "Attachments have been uploaded to this shipment.", "attachments": [ { "path": "attachments/EZDXv1TmvIOkBKjysyDSiM8keDjs16yP5dYp661c1D6MUSCqSyib0LEydAzWirell2ZauIlBo3AG877UUYGZpcOiKp4cUW7wz9tzvFW13swQLPebryR4Lyxe.png", "name": "Manifest.xml", "url": "http://localhost:3001/storage/attachments/EZDXv1TmvIOkBKjysyDSiM8keDjs16yP5dYp661c1D6MUSCqSyib0LEydAzWirell2ZauIlBo3AG877UUYGZpcOiKp4cUW7wz9tzvFW13swQLPebryR4Lyxe.png", "attachable_id": 15, "attachable_type": "outbound-shipment", "updated_at": "2024-05-29T12:39:06.000000Z", "created_at": "2024-05-29T12:39:06.000000Z", "id": 1 } ] } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/shipments/outbound/{outbound_shipment}/outbound-shipment-item": { "get": { "summary": "List items in an outbound shipment", "operationId": "list-outbound-shipment-items", "tags": [ "Outbound Shipments" ], "parameters": [ { "name": "outbound_shipment", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the outbound shipment", "example": 1 } } ], "responses": { "200": { "description": "A successful response returning the list of items in the outbound shipment", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of items in the outbound shipment", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier for the outbound shipment item", "example": 1 }, "item_id": { "type": "integer", "description": "The ID of the inventory item", "example": 1 }, "quantity": { "type": "integer", "description": "The quantity of the item in this shipment", "example": 10 }, "expiry_date": { "type": [ "string", "null" ], "description": "The expiry date for this item in YYYY-MM-DD format", "example": "2025-01-01" } }, "required": [ "id", "item_id", "quantity" ] } } }, "required": [ "items" ] }, "examples": { "example": { "value": { "items": [ { "id": 1387, "created_at": "2024-04-08T10:30:57.000000Z", "updated_at": "2024-04-08T10:30:57.000000Z", "shipment_id": 1455, "item_id": 3375, "quantity": 80, "expiry_date": null, "cost_per_item": 17.93, "item": { "id": 3375, "merchant_sku": "Mediocre-Ir-932762", "title": "Mediocre Iron Shoes", "condition": "new", "fnsku": "X0008OG4VD", "asin": "B01MRL790Q" }, "item_group_configurations": [], "moves": [], "company_services": [] } ] } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" } } }, "post": { "summary": "Add an item to an outbound shipment", "operationId": "create-outbound-shipment-item", "tags": [ "Outbound Shipments" ], "parameters": [ { "name": "outbound_shipment", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the outbound shipment", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "item_id": { "type": "integer", "description": "The ID of the inventory item to add", "example": 1 }, "quantity": { "type": "integer", "description": "The quantity of the item to add", "example": 10 }, "expiry_date": { "type": [ "string", "null" ], "description": "The expiry date for this item in YYYY-MM-DD format", "example": "2025-01-01" } }, "required": [ "item_id", "quantity" ] } } } }, "responses": { "200": { "description": "A successful response after adding the item to the shipment", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Item added to shipment" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Item added to shipment" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/shipments/outbound/{outbound_shipment}/outbound-shipment-item/{outbound_shipment_item}": { "patch": { "summary": "Update an item in an outbound shipment", "operationId": "update-outbound-shipment-item", "tags": [ "Outbound Shipments" ], "parameters": [ { "name": "outbound_shipment", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the outbound shipment", "example": 1 } }, { "name": "outbound_shipment_item", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the outbound shipment item", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quantity": { "type": [ "integer", "null" ], "description": "The updated quantity of the item", "example": 10 }, "expiry_date": { "type": [ "string", "null" ], "description": "The updated expiry date in YYYY-MM-DD format", "example": "2025-01-01" } } } } } }, "responses": { "200": { "description": "A successful response after updating the item", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Item updated" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Item updated" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } }, "delete": { "summary": "Remove an item from an outbound shipment", "operationId": "delete-outbound-shipment-item", "tags": [ "Outbound Shipments" ], "parameters": [ { "name": "outbound_shipment", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the outbound shipment", "example": 1 } }, { "name": "outbound_shipment_item", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the outbound shipment item", "example": 1 } } ], "responses": { "200": { "description": "A successful response after deleting the item", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Item deleted" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Item deleted" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" } } } }, "/fba-transport/v2024/plans": { "get": { "summary": "List FBA transport v2024 plans", "operationId": "list-fba-transport-v2024-plans", "tags": [ "FBA Transport" ], "parameters": [ { "name": "outbound_shipment_id", "in": "query", "required": false, "schema": { "type": "integer", "description": "Filter plans by outbound shipment ID", "example": 1 } } ], "responses": { "200": { "description": "A successful response returning the list of FBA transport v2024 plans", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/paths/~1fba-transport~1v2024~1plans/post/responses/200/content/application~1json/schema/properties/data" } } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": [ { "id": "019953ae-7a0d-7342-956a-881dcdbe42ad", "created_at": "2025-09-16T17:59:28.000000Z", "updated_at": "2025-09-16T18:00:05.000000Z", "name": "Eagle Eye Engineering", "ship_from_address": { "name": "AL Warehouse", "address_line_1": "1300 Montgomery Highway", "address_line_2": "Suite 109", "company_name": null, "district_or_county": null, "city": "Vestavia Hills", "state_or_province_code": "AL", "country_code": "US", "postal_code": "35216-9520", "email": null, "phone_number": "1234567890" }, "marketplace": { "identifier": "ATVPDKIKX0DER", "country": "United States" }, "outbound_shipment_id": 5, "channel_id": 1, "inbound_plan_id": "XlJbBi51GdqP9yfQDUQA43EI0VrQ7mJdlzfLmY", "create_plan_operation_id": "019953ae-7a0d-7342-956a-881dcd7b2c81", "is_canceled": false, "using_2d_barcodes": false, "status": "ACTIVE", "items": [ { "id": "019953ae-7a0d-7342-956a-881dce3b8a23", "created_at": "2025-09-16T17:59:28.000000Z", "updated_at": "2025-09-16T17:59:29.000000Z", "msku": "Mini-Porta-276810", "fnsku": "X00SPO3LCY", "asin": "B00ZB18SIF", "quantity": 40, "label_owner": "SELLER", "prep_owner": "SELLER", "expiration": null, "manufacturing_lot_code": null } ], "packing_options": [], "is_packing_information_set": true, "isPackingInfoKnown": true, "box_groups": [], "placement_options": [] } ] } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" } } }, "post": { "summary": "Create an FBA transport v2024 shipping plan", "operationId": "create-fba-transport-v2024-plan", "description": "Creates a new Amazon FBA inbound shipping plan for an outbound shipment. The plan is created asynchronously via Amazon's Fulfillment Inbound API. Once created, use the returned plan to configure packing options, placement options, and transportation options before confirming the shipment.", "tags": [ "FBA Transport" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "outbound_shipment_id": { "type": "integer", "description": "The ID of the outbound shipment to create a plan for", "example": 5 }, "channel_id": { "type": "integer", "description": "The ID of the Amazon channel (must be an active Amazon channel)", "example": 1 }, "destination_marketplace": { "type": [ "string", "null" ], "description": "The Amazon marketplace identifier for the destination (e.g. ATVPDKIKX0DER for US). Defaults to the channel's marketplace if not provided.", "example": "ATVPDKIKX0DER" }, "items": { "type": "array", "description": "The items to include in the shipping plan", "minItems": 1, "items": { "type": "object", "properties": { "msku": { "type": "string", "description": "The merchant SKU for this item", "minLength": 1, "maxLength": 40, "example": "Mini-Porta-276810" }, "quantity": { "type": "integer", "description": "The quantity of this item to include in the plan", "minimum": 1, "maximum": 10000, "example": 40 }, "label_owner": { "type": "string", "description": "Who will own the labeling responsibility for this item", "enum": [ "AMAZON", "SELLER", "NONE" ], "example": "SELLER" }, "prep_owner": { "type": "string", "description": "Who will own the prep responsibility for this item", "enum": [ "AMAZON", "SELLER" ], "example": "SELLER" }, "expiration": { "type": [ "string", "null" ], "format": "date", "description": "Optional expiration date for the item (YYYY-MM-DD)", "example": null }, "manufacturing_lot_code": { "type": [ "string", "null" ], "description": "Optional manufacturing lot code (1-256 characters)", "minLength": 1, "maxLength": 256, "example": null } }, "required": [ "msku", "quantity", "label_owner", "prep_owner" ] } } }, "required": [ "outbound_shipment_id", "channel_id", "items" ] }, "examples": { "example": { "value": { "outbound_shipment_id": 5, "channel_id": 1, "destination_marketplace": "ATVPDKIKX0DER", "items": [ { "msku": "Mini-Porta-276810", "quantity": 40, "label_owner": "SELLER", "prep_owner": "SELLER", "expiration": null, "manufacturing_lot_code": null } ] } } } } } }, "responses": { "200": { "description": "A successful response returning the newly created FBA transport v2024 plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the FBA transport v2024 plan", "example": "plan_abc123" }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the plan was created", "example": "2024-01-01T00:00:00Z" }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the plan was last updated", "example": "2024-01-01T00:00:00Z" }, "name": { "type": [ "string", "null" ], "description": "The name of the FBA transport plan" }, "outbound_shipment_id": { "type": "integer", "description": "The ID of the associated outbound shipment" }, "channel_id": { "type": [ "integer", "null" ], "description": "The ID of the associated channel" }, "inbound_plan_id": { "type": [ "string", "null" ], "description": "The Amazon inbound plan ID", "example": "inboundPlanId-abc123" }, "create_plan_operation_id": { "type": [ "string", "null" ], "description": "The ID of the create plan operation" }, "is_canceled": { "type": "boolean", "description": "Whether the plan has been canceled" }, "using_2d_barcodes": { "type": "boolean", "description": "Whether the plan uses 2D barcodes" }, "status": { "type": [ "string", "null" ], "description": "The current status of the plan" }, "ship_from_address": { "type": "object", "description": "The address the shipment is being sent from" }, "marketplace": { "type": "object", "description": "The Amazon marketplace for this plan", "properties": { "identifier": { "type": "string", "description": "The marketplace identifier", "example": "ATVPDKIKX0DER" }, "country": { "type": "string", "description": "The country name for the marketplace", "example": "United States" } }, "additionalProperties": false, "required": [ "identifier", "country" ] }, "items": { "type": "array", "description": "The items in this plan", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the plan item" }, "msku": { "type": [ "string", "null" ], "description": "The merchant SKU" }, "fnsku": { "type": [ "string", "null" ], "description": "The fulfillment network SKU" }, "asin": { "type": [ "string", "null" ], "description": "The Amazon Standard Identification Number" }, "quantity": { "type": "integer", "description": "The quantity of this item in the plan" }, "label_owner": { "type": "string", "description": "The owner of the label" }, "prep_owner": { "type": "string", "description": "The owner of the prep" }, "expiration": { "type": [ "string", "null" ], "description": "The expiration date of the item" }, "manufacturing_lot_code": { "type": [ "string", "null" ], "description": "The manufacturing lot code" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp of when the plan item was created" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp of when the plan item was last updated" } }, "additionalProperties": false, "required": [ "id", "quantity", "label_owner", "prep_owner" ] } }, "packing_options": { "type": "array", "description": "The packing options for this plan", "items": { "type": "object" } }, "box_groups": { "type": "array", "description": "The box groups for this plan", "items": { "type": "object" } }, "placement_options": { "type": "array", "description": "The placement options for this plan", "items": { "type": "object" } }, "is_packing_information_set": { "type": "boolean", "description": "Whether packing information has been set for this plan" }, "isPackingInfoKnown": { "type": "boolean", "description": "Whether packing info is known for this plan" } }, "additionalProperties": false, "required": [ "id", "outbound_shipment_id", "is_canceled", "using_2d_barcodes", "items", "packing_options", "box_groups", "placement_options", "is_packing_information_set", "isPackingInfoKnown" ] } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "id": "019953ae-7a0d-7342-956a-881dcdbe42ad", "created_at": "2025-09-16T17:59:28.000000Z", "updated_at": "2025-09-16T18:00:05.000000Z", "name": "Eagle Eye Engineering", "ship_from_address": { "name": "AL Warehouse", "address_line_1": "1300 Montgomery Highway", "address_line_2": "Suite 109", "company_name": null, "district_or_county": null, "city": "Vestavia Hills", "state_or_province_code": "AL", "country_code": "US", "postal_code": "35216-9520", "email": null, "phone_number": "1234567890" }, "marketplace": { "identifier": "ATVPDKIKX0DER", "country": "United States" }, "outbound_shipment_id": 5, "channel_id": 1, "inbound_plan_id": "XlJbBi51GdqP9yfQDUQA43EI0VrQ7mJdlzfLmY", "create_plan_operation_id": "019953ae-7a0d-7342-956a-881dcd7b2c81", "is_canceled": false, "using_2d_barcodes": false, "status": "ACTIVE", "items": [ { "id": "019953ae-7a0d-7342-956a-881dce3b8a23", "created_at": "2025-09-16T17:59:28.000000Z", "updated_at": "2025-09-16T17:59:29.000000Z", "msku": "Mini-Porta-276810", "fnsku": "X00SPO3LCY", "asin": "B00ZB18SIF", "quantity": 40, "label_owner": "SELLER", "prep_owner": "SELLER", "expiration": null, "manufacturing_lot_code": null } ], "packing_options": [], "is_packing_information_set": false, "isPackingInfoKnown": false, "box_groups": [], "placement_options": [] } } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/fba-transport/v2024/plans/{plan}": { "get": { "summary": "Get a FBA transport v2024 plan", "operationId": "get-fba-transport-v2024-plan", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "plan_abc123" } } ], "responses": { "200": { "description": "A successful response returning the FBA transport v2024 plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/paths/~1fba-transport~1v2024~1plans/post/responses/200/content/application~1json/schema/properties/data" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "id": "019953ae-7a0d-7342-956a-881dcdbe42ad", "created_at": "2025-09-16T17:59:28.000000Z", "updated_at": "2025-09-16T18:00:05.000000Z", "name": "Eagle Eye Engineering", "ship_from_address": { "name": "AL Warehouse", "address_line_1": "1300 Montgomery Highway", "address_line_2": "Suite 109", "company_name": null, "district_or_county": null, "city": "Vestavia Hills", "state_or_province_code": "AL", "country_code": "US", "postal_code": "35216-9520", "email": null, "phone_number": "1234567890" }, "marketplace": { "identifier": "ATVPDKIKX0DER", "country": "United States" }, "outbound_shipment_id": 5, "channel_id": 1, "inbound_plan_id": "XlJbBi51GdqP9yfQDUQA43EI0VrQ7mJdlzfLmY", "create_plan_operation_id": "019953ae-7a0d-7342-956a-881dcd7b2c81", "is_canceled": false, "using_2d_barcodes": false, "status": "ACTIVE", "items": [ { "id": "019953ae-7a0d-7342-956a-881dce3b8a23", "created_at": "2025-09-16T17:59:28.000000Z", "updated_at": "2025-09-16T17:59:29.000000Z", "msku": "Mini-Porta-276810", "fnsku": "X00SPO3LCY", "asin": "B00ZB18SIF", "quantity": 40, "label_owner": "SELLER", "prep_owner": "SELLER", "expiration": null, "manufacturing_lot_code": null } ], "packing_options": [ { "id": "019953ae-8047-71b6-8214-cafa0b1eff32", "discounts": [], "expiration": null, "fees": [], "packing_option_id": "pocajn494QJgzId4JWtXCLdl1OyIEeR07fzOk7", "status": "OFFERED", "supported_shipping_configurations": [], "confirmed_at": "2025-09-16T17:59:31.000000Z", "packing_groups": [] } ], "is_packing_information_set": true, "box_groups": [], "placement_options": [] } } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" } } } }, "/fba-transport/v2024/plans/{plan}/labels": { "get": { "summary": "Get shipment labels for an FBA transport v2024 plan", "operationId": "get-fba-transport-v2024-plan-labels", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "plan_abc123" } }, { "name": "shipment_id", "in": "query", "required": true, "schema": { "type": "string", "description": "The Amazon shipment ID to retrieve labels for", "example": "shipment_abc123" } } ], "responses": { "200": { "description": "A successful response returning the labels for the shipment", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "The labels for the shipment", "items": { "type": "object" } } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": [ { "id": "019b2286-9fee-71de-9f64-154824d3aa4d", "created_at": "2025-12-15T15:00:07.000000Z", "updated_at": "2025-12-15T15:00:07.000000Z", "name": "Amazon Package/Carton Labels (8.5\" x 11\")", "url": "http://demo.conveyr.test/storage/fba-transport/SH-CONFIRM001/amazon-packagecarton-labels-85-x-11.pdf", "type": "package", "paper_size": "PackageLabel_Letter_2" } ] } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/fba-transport/v2024/plans/{plan}/box-groups": { "post": { "summary": "Create a box group for an FBA plan", "operationId": "create-fba-transport-v2024-box-group", "description": "Creates a new box group defining the dimensions, weight, and associated packing entity for boxes in an FBA transport plan. Items (SKUs) and the number of physical boxes are configured separately after creation.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "associated_entity_id": { "type": "string", "description": "The Amazon packing group ID or shipment ID this box group belongs to", "example": "packingGroupId-abc123" }, "length_mm": { "type": "integer", "description": "The interior length of the box in millimetres", "minimum": 1, "maximum": 12700, "example": 300 }, "width_mm": { "type": "integer", "description": "The interior width of the box in millimetres", "minimum": 1, "maximum": 12700, "example": 200 }, "height_mm": { "type": "integer", "description": "The interior height of the box in millimetres", "minimum": 1, "maximum": 12700, "example": 150 }, "weight_gm": { "type": "integer", "description": "The total weight of a packed box in grams", "minimum": 1, "maximum": 685000, "example": 5000 } }, "required": [ "associated_entity_id", "length_mm", "width_mm", "height_mm", "weight_gm" ] }, "examples": { "example": { "value": { "associated_entity_id": "packingGroupId-abc123", "length_mm": 300, "width_mm": 200, "height_mm": 150, "weight_gm": 5000 } } } } } }, "responses": { "200": { "description": "The newly created box group", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the box group", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" }, "length_mm": { "type": "integer", "description": "The length of the box in millimetres", "example": 300 }, "width_mm": { "type": "integer", "description": "The width of the box in millimetres", "example": 200 }, "height_mm": { "type": "integer", "description": "The height of the box in millimetres", "example": 150 }, "weight_gm": { "type": "integer", "description": "The weight of a packed box in grams", "example": 5000 }, "packing_group_id": { "type": "string", "description": "The Amazon packing group ID or shipment ID this box group is associated with", "example": "packingGroupId-abc123" }, "box_numbers": { "type": "array", "description": "The sequential box numbers assigned to individual boxes in this group", "items": { "type": "integer" }, "example": [ 1, 2, 3 ] }, "items": { "type": "array", "description": "The items (SKUs) packed into each box in this group", "items": { "$ref": "#/paths/~1fba-transport~1v2024~1plans~1%7Bplan%7D~1box-groups~1%7Bbox_group_id%7D~1items/post/responses/200/content/application~1json/schema/properties/box_group_item" } } }, "additionalProperties": false, "required": [ "id", "length_mm", "width_mm", "height_mm", "weight_gm", "packing_group_id", "box_numbers", "items" ] } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "id": "019953ae-7a0d-7342-956a-881dcdbe42ad", "length_mm": 300, "width_mm": 200, "height_mm": 150, "weight_gm": 5000, "packing_group_id": "packingGroupId-abc123", "box_numbers": [], "items": [] } } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/fba-transport/v2024/plans/{plan}/box-groups/{box_group_id}": { "put": { "summary": "Update a box group", "operationId": "update-fba-transport-v2024-box-group", "description": "Updates the dimensions and weight of a box group. Cannot be called after packing information has been submitted — reset submissions first.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } }, { "name": "box_group_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the box group", "example": "019953ae-8047-71b6-8214-cafa0b1eff32" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "length_mm": { "type": "integer", "description": "The interior length of the box in millimetres", "minimum": 1, "maximum": 12700, "example": 350 }, "width_mm": { "type": "integer", "description": "The interior width of the box in millimetres", "minimum": 1, "maximum": 12700, "example": 250 }, "height_mm": { "type": "integer", "description": "The interior height of the box in millimetres", "minimum": 1, "maximum": 12700, "example": 180 }, "weight_gm": { "type": "integer", "description": "The total weight of a packed box in grams", "minimum": 1, "maximum": 685000, "example": 6000 } }, "required": [ "length_mm", "width_mm", "height_mm", "weight_gm" ] }, "examples": { "example": { "value": { "length_mm": 350, "width_mm": 250, "height_mm": 180, "weight_gm": 6000 } } } } } }, "responses": { "200": { "description": "Box group updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Box group updated" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Box group updated" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } }, "delete": { "summary": "Remove a box group", "operationId": "remove-fba-transport-v2024-box-group", "description": "Permanently deletes a box group and all of its boxes and items.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } }, { "name": "box_group_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the box group", "example": "019953ae-8047-71b6-8214-cafa0b1eff32" } } ], "responses": { "200": { "description": "Box group removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Box group removed" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Box group removed" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" } } } }, "/fba-transport/v2024/plans/{plan}/box-groups/{box_group_id}/set-box-quantity": { "post": { "summary": "Set the number of boxes in a box group", "operationId": "set-fba-transport-v2024-box-quantity", "description": "Sets the number of physical boxes in a box group. Increasing the quantity creates new boxes with sequentially assigned numbers across all box groups in the plan. Decreasing the quantity removes the newest boxes.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } }, { "name": "box_group_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the box group", "example": "019953ae-8047-71b6-8214-cafa0b1eff32" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quantity": { "type": "integer", "description": "The number of physical boxes in this group", "minimum": 1, "example": 5 } }, "required": [ "quantity" ] }, "examples": { "example": { "value": { "quantity": 5 } } } } } }, "responses": { "200": { "description": "Box quantity updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Box quantity updated" }, "box_numbers": { "type": "array", "description": "The sequential box numbers now assigned to boxes in this group", "items": { "type": "integer" }, "example": [ 1, 2, 3, 4, 5 ] } }, "required": [ "message", "box_numbers" ] }, "examples": { "example": { "value": { "message": "Box quantity updated", "box_numbers": [ 1, 2, 3, 4, 5 ] } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/fba-transport/v2024/plans/{plan}/box-groups/{box_group_id}/items": { "post": { "summary": "Add an item to a box group", "operationId": "create-fba-transport-v2024-box-group-item", "description": "Adds a plan item (SKU) to a box group, specifying how many units of that SKU are packed into each box in the group. Each plan item can only appear once per box group.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } }, { "name": "box_group_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the box group", "example": "019953ae-8047-71b6-8214-cafa0b1eff32" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_item_id": { "type": "string", "description": "The ID of the plan item (SKU) to add to this box group", "example": "019953ae-7a0d-7342-956a-881dce3b8a23" }, "quantity": { "type": "integer", "description": "The number of units of this SKU packed in each box in the group", "minimum": 1, "example": 10 } }, "required": [ "plan_item_id", "quantity" ] }, "examples": { "example": { "value": { "plan_item_id": "019953ae-7a0d-7342-956a-881dce3b8a23", "quantity": 10 } } } } } }, "responses": { "200": { "description": "Item added to the box group successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "box_group_item": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the box group item", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the item was added to the box group", "example": "2024-01-01T00:00:00Z" }, "plan_item_id": { "type": "string", "description": "The ID of the plan item (SKU) packed in this box group", "example": "019953ae-7a0d-7342-956a-881dce3b8a23" }, "msku": { "type": "string", "description": "The merchant SKU packed in this box group", "example": "Mini-Porta-276810" }, "quantity": { "type": "integer", "description": "The number of units of this SKU in each box in the group", "example": 10 } }, "additionalProperties": false, "required": [ "id", "plan_item_id", "msku", "quantity" ] } }, "required": [ "box_group_item" ] }, "examples": { "example": { "value": { "box_group_item": { "id": "019953ae-7a0d-7342-956a-881dcdbe42ae", "created_at": "2024-01-01T00:00:00Z", "plan_item_id": "019953ae-7a0d-7342-956a-881dce3b8a23", "msku": "Mini-Porta-276810", "quantity": 10 } } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/fba-transport/v2024/plans/{plan}/box-groups/{box_group_id}/items/{box_group_item_id}": { "put": { "summary": "Update an item in a box group", "operationId": "update-fba-transport-v2024-box-group-item", "description": "Updates the quantity of a plan item (SKU) in a box group. Cannot be called after packing information has been submitted — reset submissions first.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } }, { "name": "box_group_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the box group", "example": "019953ae-8047-71b6-8214-cafa0b1eff32" } }, { "name": "box_group_item_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the box group item", "example": "019953ae-7a0d-7342-956a-881dcdbe42ae" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quantity": { "type": "integer", "description": "The updated number of units of this SKU packed in each box in the group", "minimum": 1, "example": 12 } }, "required": [ "quantity" ] }, "examples": { "example": { "value": { "quantity": 12 } } } } } }, "responses": { "200": { "description": "Item updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "box_group_item": { "$ref": "#/paths/~1fba-transport~1v2024~1plans~1%7Bplan%7D~1box-groups~1%7Bbox_group_id%7D~1items/post/responses/200/content/application~1json/schema/properties/box_group_item" }, "message": { "type": "string", "example": "Item updated" } }, "required": [ "box_group_item", "message" ] }, "examples": { "example": { "value": { "box_group_item": { "id": "019953ae-7a0d-7342-956a-881dcdbe42ae", "created_at": "2024-01-01T00:00:00Z", "plan_item_id": "019953ae-7a0d-7342-956a-881dce3b8a23", "msku": "Mini-Porta-276810", "quantity": 12 }, "message": "Item updated" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } }, "delete": { "summary": "Remove an item from a box group", "operationId": "remove-fba-transport-v2024-box-group-item", "description": "Removes a plan item (SKU) from a box group.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } }, { "name": "box_group_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the box group", "example": "019953ae-8047-71b6-8214-cafa0b1eff32" } }, { "name": "box_group_item_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the box group item", "example": "019953ae-7a0d-7342-956a-881dcdbe42ae" } } ], "responses": { "200": { "description": "Item removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Item removed" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Item removed" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/fba-transport/v2024/plans/{plan}/set-packing-information": { "post": { "summary": "Submit box contents to Amazon", "operationId": "set-fba-transport-v2024-packing-information", "description": "Submits the plan's box contents (box groups, dimensions, weights, and items) to Amazon's Fulfillment Inbound API as packing information. The plan must have a confirmed packing option (when packing info is known) or a confirmed placement option (when packing info is unknown), and all box groups must have at least one item. Returns an operation ID that can be polled to check completion.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } }, "required": [ "plan_id" ] }, "examples": { "example": { "value": { "plan_id": "019953ae-7a0d-7342-956a-881dcdbe42ad" } } } } } }, "responses": { "200": { "description": "Packing information submitted successfully. The response body contains the operation ID as a plain text string.", "content": { "text/plain": { "schema": { "type": "string", "description": "The ID of the created operation, used to poll for completion", "example": "019953ae-8047-71b6-8214-cafa0b1eff32" } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/fba-transport/v2024/plans/{plan}/reset-submissions": { "post": { "summary": "Reset packing information submissions", "operationId": "reset-fba-transport-v2024-submissions", "description": "Clears the packing information submission from the plan, allowing box contents to be modified and re-submitted.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } } ], "responses": { "200": { "description": "Submissions reset successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Submissions reset" } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" } } } }, "/fba-transport/v2024/plans/{plan}/generate-placement-options": { "post": { "summary": "Generate placement options for an FBA plan", "operationId": "generate-fba-transport-v2024-placement-options", "description": "Triggers an asynchronous operation to generate placement options (fulfilment centre assignments) from Amazon for the plan. Poll the returned operation ID until complete, then call GET /placement-options to retrieve the results.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } }, "required": [ "plan_id" ] } } } }, "responses": { "200": { "description": "Operation created. The response body is the operation ID as plain text.", "content": { "text/plain": { "schema": { "type": "string", "example": "019953ae-8047-71b6-8214-cafa0b1eff32" } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/fba-transport/v2024/plans/{plan}/placement-options": { "get": { "summary": "Fetch placement options from Amazon", "operationId": "fetch-fba-transport-v2024-placement-options", "description": "Pulls the latest placement options from Amazon and stores them on the plan. Call this after the generate-placement-options operation completes. View the resulting options via the plan resource.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } } ], "responses": { "200": { "description": "Placement options fetched and stored on the plan successfully." }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/fba-transport/v2024/plans/{plan}/select-placement-option": { "post": { "summary": "Select a placement option", "operationId": "select-fba-transport-v2024-placement-option", "description": "Marks a placement option as selected locally. This does not submit anything to Amazon — call confirm-placement-option to submit the selection.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" }, "placement_option_id": { "type": "string", "description": "The Amazon placement option ID to select", "example": "placementOptionId-abc123" } }, "required": [ "plan_id", "placement_option_id" ] } } } }, "responses": { "200": { "description": "Placement option selected successfully." }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/fba-transport/v2024/plans/{plan}/confirm-placement-option": { "post": { "summary": "Confirm a placement option with Amazon", "operationId": "confirm-fba-transport-v2024-placement-option", "description": "Submits the selected placement option to Amazon asynchronously. Poll the returned operation ID until complete, then call mark-placement-option-as-confirmed to update local state.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" }, "placement_option_id": { "type": "string", "description": "The Amazon placement option ID to confirm", "example": "placementOptionId-abc123" } }, "required": [ "plan_id", "placement_option_id" ] } } } }, "responses": { "200": { "description": "Operation created. The response body is the operation ID as plain text.", "content": { "text/plain": { "schema": { "type": "string", "example": "019953ae-8047-71b6-8214-cafa0b1eff32" } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/fba-transport/v2024/plans/{plan}/mark-placement-option-as-confirmed": { "post": { "summary": "Mark a placement option as confirmed", "operationId": "mark-fba-transport-v2024-placement-option-as-confirmed", "description": "Updates local state to reflect that Amazon has confirmed the placement option. Call this after the confirm-placement-option operation completes successfully.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" }, "placement_option_id": { "type": "string", "description": "The Amazon placement option ID to mark as confirmed", "example": "placementOptionId-abc123" } }, "required": [ "plan_id", "placement_option_id" ] } } } }, "responses": { "200": { "description": "Placement option marked as confirmed successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Placement option confirmed successfully" } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/fba-transport/v2024/plans/{plan}/reset-placement-options": { "post": { "summary": "Reset placement options for an FBA plan", "operationId": "reset-fba-transport-v2024-placement-options", "description": "Clears all placement options from the plan, allowing them to be regenerated.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } } ], "responses": { "200": { "description": "Placement options reset successfully." }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" } } } }, "/fba-transport/v2024/plans/{plan}/generate-delivery-window-options": { "post": { "summary": "Generate delivery window options for a shipment", "operationId": "generate-fba-transport-v2024-delivery-window-options", "description": "Triggers an asynchronous operation to generate delivery window options for a specific shipment from Amazon. Poll the returned operation ID until complete, then call GET /delivery-window-options to retrieve the results.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" }, "shipment_id": { "type": "string", "description": "The Amazon shipment ID to generate delivery windows for", "example": "shipmentId-abc123" } }, "required": [ "plan_id", "shipment_id" ] } } } }, "responses": { "200": { "description": "Operation created. The response body is the operation ID as plain text.", "content": { "text/plain": { "schema": { "type": "string", "example": "019953ae-8047-71b6-8214-cafa0b1eff32" } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/fba-transport/v2024/plans/{plan}/delivery-window-options": { "get": { "summary": "Fetch delivery window options from Amazon", "operationId": "fetch-fba-transport-v2024-delivery-window-options", "description": "Pulls the latest delivery window options from Amazon for a specific shipment and stores them locally. Call this after the generate-delivery-window-options operation completes.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } }, { "name": "plan_id", "in": "query", "required": true, "schema": { "type": "string", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } }, { "name": "placement_option_id", "in": "query", "required": true, "schema": { "type": "string", "example": "placementOptionId-abc123" } }, { "name": "shipment_id", "in": "query", "required": true, "schema": { "type": "string", "example": "shipmentId-abc123" } } ], "responses": { "200": { "description": "Delivery window options fetched and stored successfully." }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/fba-transport/v2024/plans/{plan}/confirm-delivery-window-option": { "post": { "summary": "Confirm a delivery window option with Amazon", "operationId": "confirm-fba-transport-v2024-delivery-window-option", "description": "Submits the selected delivery window option for a shipment to Amazon asynchronously. Poll the returned operation ID until complete, then call mark-delivery-window-option-as-confirmed.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" }, "shipment_id": { "type": "string", "description": "The Amazon shipment ID", "example": "shipmentId-abc123" }, "delivery_window_option_id": { "type": "string", "description": "The Amazon delivery window option ID to confirm", "example": "deliveryWindowOptionId-abc123" } }, "required": [ "plan_id", "shipment_id", "delivery_window_option_id" ] } } } }, "responses": { "200": { "description": "Operation created. The response body is the operation ID as plain text.", "content": { "text/plain": { "schema": { "type": "string", "example": "019953ae-8047-71b6-8214-cafa0b1eff32" } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/fba-transport/v2024/plans/{plan}/mark-delivery-window-option-as-confirmed": { "post": { "summary": "Mark a delivery window option as confirmed", "operationId": "mark-fba-transport-v2024-delivery-window-option-as-confirmed", "description": "Updates local state to reflect that Amazon has confirmed the delivery window option. Call this after the confirm-delivery-window-option operation completes successfully.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" }, "shipment_id": { "type": "string", "description": "The Amazon shipment ID", "example": "shipmentId-abc123" }, "delivery_window_option_id": { "type": "string", "description": "The Amazon delivery window option ID to mark as confirmed", "example": "deliveryWindowOptionId-abc123" } }, "required": [ "plan_id", "shipment_id", "delivery_window_option_id" ] } } } }, "responses": { "200": { "description": "Delivery window option marked as confirmed successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Delivery window option confirmed successfully" } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/fba-transport/v2024/plans/{plan}/generate-transportation-options": { "post": { "summary": "Generate transportation options for shipments", "operationId": "generate-fba-transport-v2024-transportation-options", "description": "Triggers an asynchronous operation to generate transportation options (carrier and mode selections) from Amazon for one or more shipments. Poll the returned operation ID until complete, then call GET /transportation-options to fetch the results.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" }, "placement_option_id": { "type": "string", "description": "The Amazon placement option ID", "example": "placementOptionId-abc123" }, "shipments_dates": { "type": "array", "description": "The shipments and their earliest ready-to-ship dates", "items": { "type": "object", "properties": { "shipment_id": { "type": "string", "description": "The Amazon shipment ID", "example": "shipmentId-abc123" }, "start_date": { "type": "string", "description": "The earliest date the shipment will be ready (ISO 8601)", "example": "2024-06-01" } }, "required": [ "shipment_id", "start_date" ] } } }, "required": [ "plan_id", "placement_option_id", "shipments_dates" ] } } } }, "responses": { "200": { "description": "Operation created. The response body is the operation ID as plain text.", "content": { "text/plain": { "schema": { "type": "string", "example": "019953ae-8047-71b6-8214-cafa0b1eff32" } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/fba-transport/v2024/plans/{plan}/transportation-options": { "get": { "summary": "Fetch transportation options from Amazon", "operationId": "fetch-fba-transport-v2024-transportation-options", "description": "Pulls the latest transportation options from Amazon for a specific shipment and stores them locally. Call this after the generate-transportation-options operation completes.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } }, { "name": "plan_id", "in": "query", "required": true, "schema": { "type": "string", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } }, { "name": "placement_option_id", "in": "query", "required": true, "schema": { "type": "string", "example": "placementOptionId-abc123" } }, { "name": "shipment_id", "in": "query", "required": true, "schema": { "type": "string", "example": "shipmentId-abc123" } } ], "responses": { "200": { "description": "Transportation options fetched and stored successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Transportation options fetched successfully" } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/fba-transport/v2024/plans/{plan}/confirm-transportation-option": { "post": { "summary": "Confirm transportation options with Amazon", "operationId": "confirm-fba-transport-v2024-transportation-option", "description": "Submits the selected transportation options (carrier and mode) for one or more shipments to Amazon asynchronously. Poll the returned operation ID until complete, then call mark-transportation-option-as-confirmed.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" }, "shipment_transportation_ids": { "type": "array", "description": "The shipment and transportation option ID pairs to confirm", "items": { "type": "object", "properties": { "shipment_id": { "type": "string", "description": "The Amazon shipment ID", "example": "shipmentId-abc123" }, "transportation_option_id": { "type": "string", "description": "The Amazon transportation option ID to confirm", "example": "transportationOptionId-abc123" } }, "required": [ "shipment_id", "transportation_option_id" ] } } }, "required": [ "plan_id", "shipment_transportation_ids" ] } } } }, "responses": { "200": { "description": "Operation created. The response body is the operation ID as plain text.", "content": { "text/plain": { "schema": { "type": "string", "example": "019953ae-8047-71b6-8214-cafa0b1eff32" } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/fba-transport/v2024/plans/{plan}/mark-transportation-option-as-confirmed": { "post": { "summary": "Mark transportation options as confirmed", "operationId": "mark-fba-transport-v2024-transportation-option-as-confirmed", "description": "Updates local state to reflect that Amazon has confirmed the transportation options. Call this after the confirm-transportation-option operation completes successfully.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "plan", "in": "path", "required": true, "schema": { "type": "string", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string", "description": "The ID of the FBA transport v2024 plan", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" }, "shipment_transportation_ids": { "type": "array", "description": "The shipment and transportation option ID pairs to mark as confirmed", "items": { "type": "object", "properties": { "shipment_id": { "type": "string", "description": "The Amazon shipment ID", "example": "shipmentId-abc123" }, "transportation_option_id": { "type": "string", "description": "The Amazon transportation option ID", "example": "transportationOptionId-abc123" } }, "required": [ "shipment_id", "transportation_option_id" ] } } }, "required": [ "plan_id", "shipment_transportation_ids" ] } } } }, "responses": { "200": { "description": "Transportation options marked as confirmed successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Transportation option confirmed successfully" } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/fba-transport/v2024/operations/{operation}": { "get": { "summary": "Get an FBA transport operation", "operationId": "get-fba-transport-v2024-operation", "description": "Returns the current state of an async FBA transport operation. Use this to poll for completion after calling any endpoint that returns an operation ID.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "operation", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the operation", "example": "019953ae-8047-71b6-8214-cafa0b1eff32" } } ], "responses": { "200": { "description": "The operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the operation", "example": "019953ae-8047-71b6-8214-cafa0b1eff32" }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the operation was created", "example": "2024-01-01T00:00:00Z" }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the operation was last updated", "example": "2024-01-01T00:00:05Z" }, "channel_id": { "type": "integer", "description": "The ID of the channel associated with this operation", "example": 1 }, "operation_id": { "type": "string", "description": "The Amazon operation ID returned by the FBA Inbound API", "example": "XlJbBi51GdqP9yfQDUQA43EI0VrQ7mJdlzfLmY" }, "status": { "type": [ "string", "null" ], "description": "The current status of the operation (e.g. SUCCESS, FAILED, IN_PROGRESS)", "example": "SUCCESS" }, "description": { "type": [ "string", "null" ], "description": "A description of what the operation was performing", "example": "setPackingInformation" }, "problems": { "type": [ "array", "null" ], "description": "Any problems returned by Amazon for this operation", "items": { "type": "object" } } }, "additionalProperties": false, "required": [ "id", "channel_id", "operation_id" ] } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "id": "019953ae-8047-71b6-8214-cafa0b1eff32", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:05Z", "channel_id": 1, "operation_id": "XlJbBi51GdqP9yfQDUQA43EI0VrQ7mJdlzfLmY", "status": "SUCCESS", "description": "setPackingInformation", "problems": null } } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" } } } }, "/fba-transport/v2024/operations/{operation}/update": { "get": { "summary": "Fetch an operation status update from Amazon", "operationId": "fetch-fba-transport-v2024-operation-update", "description": "Pulls the latest status for an operation from Amazon and updates local state. Returns the updated operation.", "tags": [ "FBA Transport" ], "parameters": [ { "name": "operation", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the operation", "example": "019953ae-8047-71b6-8214-cafa0b1eff32" } } ], "responses": { "200": { "description": "The updated operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/paths/~1fba-transport~1v2024~1operations~1%7Boperation%7D/get/responses/200/content/application~1json/schema/properties/data" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" } } } }, "/orders": { "get": { "summary": "List orders", "operationId": "list-orders", "tags": [ "Orders" ], "parameters": [ { "name": "fulfillable", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Filter to only return fulfillable orders" } } ], "responses": { "200": { "description": "A successful response returning the list of orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "description": "The list of orders", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier for the order", "example": 1 }, "status": { "type": [ "string", "null" ], "description": "The current status of the order", "example": "pending" }, "channel_order_id": { "type": [ "string", "null" ], "description": "The order ID from the sales channel", "example": "ORDER-123" }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the order was created", "example": "2024-01-01T00:00:00Z" }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the order was last updated", "example": "2024-01-01T00:00:00Z" }, "order_items": { "type": "array", "description": "The items in this order", "items": { "type": "object" } }, "customer": { "type": [ "object", "null" ], "description": "The customer for this order" }, "tags": { "type": "array", "description": "The tags for this order", "items": { "type": "object" } }, "searchable_identifiers": { "type": [ "string", "null" ], "description": "A comma-separated string of searchable identifiers for this order" } }, "required": [ "id" ] } } }, "required": [ "orders" ] }, "examples": { "example": { "value": { "orders": [ { "id": 1, "created_at": "2022-03-22T13:02:07.000000Z", "updated_at": "2022-03-22T13:02:07.000000Z", "customer_id": 1, "order_id": "AYV-411841-64", "channel_id": 1, "channel_order_id": "CGZ-211973-62", "order_date": "2022-03-19 09:02:06", "ship_by": "2022-03-23 09:02:06", "arrive_by": "2022-03-25 09:02:06", "status": "pending", "should_fulfill": true, "order_items_count": 1, "order_items": [], "customer": { "id": 1, "name": "Paucek, Nicolas and Kihn" } } ] } } } } } }, "401": { "description": "Unauthenticated — no valid API token was provided" }, "403": { "description": "Forbidden — you do not have permission to access this resource" } } } }, "/orders/upload": { "post": { "summary": "Upload orders", "operationId": "upload-orders", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel_id": { "type": "integer", "description": "The ID of the channel to upload orders for", "example": 1 }, "orders": { "type": "array", "description": "The list of orders to upload", "items": { "type": "object" } } }, "required": [ "orders" ] } } } }, "responses": { "200": { "description": "A successful response after uploading the orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Orders uploaded" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Orders uploaded" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/orders/{order}": { "get": { "summary": "Get an order", "operationId": "get-order", "tags": [ "Orders" ], "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the order", "example": 1 } } ], "responses": { "200": { "description": "A successful response returning the order with its relations", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "object", "description": "The order data", "properties": { "id": { "type": "integer", "description": "The unique identifier for the order", "example": 1 }, "status": { "type": [ "string", "null" ], "description": "The current status of the order", "example": "pending" }, "order_items": { "type": "array", "description": "The items in this order", "items": { "type": "object" } }, "customer": { "type": [ "object", "null" ], "description": "The customer for this order" }, "shipping_address": { "type": [ "object", "null" ], "description": "The shipping address for this order" }, "packages": { "type": "array", "description": "The packages for this order", "items": { "type": "object" } }, "attachments": { "type": "array", "description": "The attachments for this order", "items": { "type": "object" } }, "tracking_numbers": { "type": "array", "description": "The tracking numbers for this order", "items": { "type": "object" } }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the order was created", "example": "2024-01-01T00:00:00Z" }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the order was last updated", "example": "2024-01-01T00:00:00Z" } }, "required": [ "id" ] }, "fulfillment_requests": { "type": "array", "description": "The fulfillment requests for this order", "items": { "type": "object" } } }, "required": [ "order", "fulfillment_requests" ] }, "examples": { "example": { "value": { "order": { "id": 8, "created_at": "2022-09-29T20:51:03.000000Z", "updated_at": "2022-10-05T00:41:39.000000Z", "customer_id": 8, "shipping_address_id": 11, "billing_address_id": 11, "order_id": "ANX-352231-61", "channel_id": 1, "channel_order_id": "CWM-286025-86", "order_date": "2022-09-28 16:51:03", "ship_by": "2022-09-30 16:51:03", "arrive_by": "2022-10-04 16:51:03", "status": "shipped", "should_fulfill": true, "order_items": [], "customer": null, "shipping_address": null, "packages": [], "attachments": [], "tracking_numbers": [] }, "fulfillment_requests": [] } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "description": "Not Found — the requested resource does not exist" } } } }, "/orders/{order}/uploadShippingLabel": { "post": { "summary": "Upload a shipping label for an order", "operationId": "upload-order-shipping-label", "tags": [ "Orders" ], "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the order", "example": 1 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The shipping label file to upload" } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "A successful response after uploading the shipping label", "content": { "application/json": { "examples": { "example": { "value": {} } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/orders/{order}/markAsShipped": { "post": { "summary": "Mark an order as shipped", "operationId": "mark-order-as-shipped", "tags": [ "Orders" ], "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the order", "example": 1 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "tracking_number": { "type": [ "string", "null" ], "description": "The tracking number for the shipment", "example": "1Z999AA10123456784" }, "carrier": { "type": [ "string", "null" ], "description": "The carrier for the shipment", "example": "ups" }, "fulfillment_request_id": { "type": [ "string", "null" ], "description": "The ID of the fulfillment request" } } } } } }, "responses": { "200": { "description": "A successful response after marking the order as shipped", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Order marked as shipped" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Order marked as shipped" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/services": { "get": { "summary": "List company services", "operationId": "list-services", "tags": [ "Services" ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "description": "Filter services by type" } }, { "name": "archived", "in": "query", "required": false, "schema": { "type": [ "boolean", "null" ], "description": "Filter to only return archived services" } } ], "responses": { "200": { "description": "A successful response returning the list of company services", "content": { "application/json": { "schema": { "type": "object", "properties": { "services": { "type": "array", "description": "The list of company services", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier for the service", "example": 1 }, "name": { "type": "string", "description": "The name of the service", "example": "FBA Prep" }, "type": { "type": [ "string", "null" ], "description": "The type of the service", "example": "outbound_shipment_item" }, "unit": { "type": [ "string", "null" ], "description": "The unit used for pricing", "example": "bag" }, "when_to_charge": { "type": [ "string", "null" ], "description": "When the charge is applied", "example": "attached" }, "charge": { "type": [ "string", "null" ], "description": "The charge amount as a decimal string", "example": "0.1500" }, "service_provider_id": { "type": [ "integer", "null" ], "description": "The ID of the service provider this service belongs to", "example": 1 }, "price_records": { "type": "array", "description": "Historical price records for this service", "items": { "type": "object" } }, "archived_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the service was archived" }, "deleted_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the service was soft-deleted" }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the service was created", "example": "2024-01-01T00:00:00Z" }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the service was last updated", "example": "2024-01-01T00:00:00Z" } }, "required": [ "id", "name" ] } } }, "required": [ "services" ] }, "examples": { "example": { "value": { "services": [ { "id": 1, "created_at": "2024-05-09T13:22:14.000000Z", "updated_at": "2024-05-09T13:22:14.000000Z", "name": "Extra Poly Bags (1.5mm)", "type": "outbound_shipment_item", "unit": "bag", "when_to_charge": "attached", "charge": "0.1500", "advanced_options": null, "service_provider_id": 1, "price_records": [], "archived_at": null, "deleted_at": null } ] } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" } } } }, "/warehouses": { "get": { "summary": "List warehouses", "operationId": "list-warehouses", "tags": [ "Warehouses" ], "responses": { "200": { "description": "A successful response returning the list of warehouses", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "The list of warehouses", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier for the warehouse", "example": 1 }, "uuid": { "type": "string", "description": "The UUID of the warehouse", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "description": "The name of the warehouse", "example": "Main Warehouse" }, "service_provider_id": { "type": "integer", "description": "The ID of the service provider that owns this warehouse", "example": 1 }, "service_provider_uuid": { "type": [ "string", "null" ], "description": "The UUID of the service provider that owns this warehouse" }, "default_address": { "type": [ "object", "null" ], "description": "The default address of the warehouse" }, "addresses": { "type": "array", "description": "All addresses associated with the warehouse", "items": { "type": "object" } }, "default_storage_location_uuid": { "type": [ "string", "null" ], "description": "The UUID of the default storage location" }, "default_in_location_uuid": { "type": [ "string", "null" ], "description": "The UUID of the default inbound location" }, "default_out_location_uuid": { "type": [ "string", "null" ], "description": "The UUID of the default outbound location" }, "default_scrap_location_uuid": { "type": [ "string", "null" ], "description": "The UUID of the default scrap location" }, "default_adjustment_found_location_uuid": { "type": [ "string", "null" ], "description": "The UUID of the default adjustment found location" }, "default_adjustment_lost_location_uuid": { "type": [ "string", "null" ], "description": "The UUID of the default adjustment lost location" }, "default_production_in_location_uuid": { "type": [ "string", "null" ], "description": "The UUID of the default production inbound location" }, "default_production_out_location_uuid": { "type": [ "string", "null" ], "description": "The UUID of the default production outbound location" } }, "additionalProperties": false, "required": [ "id", "uuid", "name", "service_provider_id" ] } } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": [ { "id": 1, "uuid": "0197e188-5d70-8010-bf60-252ed9687632", "name": "AL Warehouse", "service_provider_id": 60983, "default_address": { "id": 1, "warehouse_id": 1, "address_line_1": "1300 Montgomery Highway", "address_line_2": "Suite 368", "address_line_3": null, "city": "Vestavia Hills", "state_province": "AL", "postal_code": "35216-5112", "country_code": "US", "phone_number": "2312312312", "is_residential": false }, "addresses": [ { "id": 1, "warehouse_id": 1, "address_line_1": "1300 Montgomery Highway", "address_line_2": "Suite 368", "address_line_3": null, "city": "Vestavia Hills", "state_province": "AL", "postal_code": "35216-5112", "country_code": "US", "phone_number": "2312312312", "is_residential": false } ] } ] } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" } } } }, "/merchants": { "get": { "summary": "List merchants", "operationId": "list-merchants", "tags": [ "Merchants" ], "responses": { "200": { "description": "A successful response returning the list of merchants", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "The list of merchants", "items": { "$ref": "#/paths/~1merchants/post/responses/200/content/application~1json/schema/properties/merchant" } } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": [ { "id": 1, "name": "Stanton-Koss", "notes": null, "primaryEmail": "larue02@example.com", "billingCycle": "monthly", "billingCycleDay": null, "perItemAdjustment": 0, "photoUrl": "https://www.gravatar.com/avatar/abc123.jpg?s=200&d=mm", "enabled": true, "isOrdersEnabled": false, "isAmazonShipmentsEnabled": false } ] } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" } } }, "post": { "summary": "Create a merchant", "operationId": "create-merchant", "tags": [ "Merchants" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the merchant", "example": "ACME Corp" }, "primary_email": { "type": [ "string", "null" ], "description": "The primary email address of the merchant", "example": "contact@acme.com" }, "invite_email": { "type": [ "string", "null" ], "description": "Email address to invite as the merchant owner. When provided, invite_role is required.", "example": "owner@acme.com" }, "invite_role": { "type": "string", "description": "Role to assign to the invited user. Required when invite_email is provided.", "enum": [ "owner" ], "example": "owner" } }, "required": [ "name", "primary_email" ] } } } }, "responses": { "200": { "description": "A successful response after creating the merchant", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Merchant created" }, "merchant": { "type": "object", "description": "NOTE: The merchant resource uses camelCase keys as that is the existing API behaviour.", "properties": { "id": { "type": "integer", "description": "The unique identifier for the merchant", "example": 1 }, "name": { "type": "string", "description": "The name of the merchant", "example": "ACME Corp" }, "notes": { "type": [ "string", "null" ], "description": "Notes for the merchant" }, "primaryEmail": { "type": [ "string", "null" ], "description": "The primary email address of the merchant", "example": "contact@acme.com" }, "billingCycle": { "type": [ "string", "null" ], "description": "The billing cycle for the merchant", "example": "monthly" }, "billingCycleDay": { "type": [ "integer", "null" ], "description": "The day of the billing cycle", "example": 1 }, "perItemAdjustment": { "type": [ "number", "null" ], "description": "The per-item adjustment for the merchant", "example": 0 }, "photoUrl": { "type": "string", "description": "The URL of the merchant's photo", "example": "https://www.gravatar.com/avatar/abc123.jpg" }, "enabled": { "type": "boolean", "description": "Whether the merchant is enabled" }, "isOrdersEnabled": { "type": "boolean", "description": "Whether orders are enabled for the merchant" }, "isAmazonShipmentsEnabled": { "type": "boolean", "description": "Whether Amazon shipments are enabled for the merchant" } }, "additionalProperties": false, "required": [ "id", "name", "photoUrl", "enabled", "isOrdersEnabled", "isAmazonShipmentsEnabled" ] } }, "required": [ "message", "merchant" ] }, "examples": { "example": { "value": { "message": "Merchant created", "merchant": { "id": 35423, "name": "Test", "notes": null, "primaryEmail": "test@test.com", "billingCycle": "monthly", "billingCycleDay": 3, "perItemAdjustment": 0, "photoUrl": "https://www.gravatar.com/avatar/abc123.jpg?s=200&d=mm", "enabled": true, "isOrdersEnabled": false, "isAmazonShipmentsEnabled": true } } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/merchants/{merchant}": { "get": { "summary": "Show a merchant", "description": "Get a single merchant by its ID.", "operationId": "show-merchant", "tags": [ "Merchants" ], "parameters": [ { "name": "merchant", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the merchant", "example": 1 } } ], "responses": { "200": { "description": "A successful response returning the merchant", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/paths/~1merchants/post/responses/200/content/application~1json/schema/properties/merchant" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "id": 1, "name": "ACME Corp", "notes": null, "primaryEmail": "contact@acme.com", "billingCycle": "monthly", "billingCycleDay": null, "perItemAdjustment": 0, "photoUrl": "https://www.gravatar.com/avatar/abc123.jpg?s=200&d=mm", "enabled": true, "isOrdersEnabled": false, "isAmazonShipmentsEnabled": false } } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" } } }, "put": { "summary": "Update a merchant", "description": "Update one or more fields on a merchant. All fields are optional.", "operationId": "update-merchant", "tags": [ "Merchants" ], "parameters": [ { "name": "merchant", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the merchant", "example": 1 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the merchant", "maxLength": 255, "example": "ACME Corp" }, "email": { "type": [ "string", "null" ], "description": "The primary email address of the merchant", "example": "contact@acme.com" }, "phone_number": { "type": [ "string", "null" ], "description": "The phone number of the merchant owner", "maxLength": 25, "example": "+1-555-0100" }, "notes": { "type": "string", "description": "Notes for the merchant", "example": "VIP customer" }, "billing_cycle": { "type": "string", "description": "The billing cycle for the merchant", "enum": [ "monthly", "manual" ], "example": "monthly" }, "billing_cycle_day": { "type": [ "integer", "null" ], "description": "The day of the billing cycle (1–28)", "minimum": 1, "maximum": 28, "example": 1 }, "per_item_adjustment": { "type": [ "number", "null" ], "description": "The per-item price adjustment", "minimum": -9.99, "maximum": 9.99, "example": 0 }, "disabled": { "type": "boolean", "description": "Whether the merchant is disabled" }, "is_orders_enabled": { "type": "boolean", "description": "Whether orders are enabled for the merchant" }, "is_amazon_shipments_enabled": { "type": "boolean", "description": "Whether Amazon shipments are enabled for the merchant" } } } } } }, "responses": { "200": { "description": "A successful response after updating the merchant", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Merchant Details Updated" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Merchant Details Updated" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/users/current": { "get": { "summary": "Get current authenticated user", "description": "Returns the currently authenticated user. Returns an empty object when unauthenticated.", "operationId": "get-current-user", "tags": [ "Users" ], "responses": { "200": { "description": "A successful response returning the current authenticated user, or an empty object when unauthenticated", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier for the user", "example": 1 }, "uuid": { "type": "string", "format": "uuid", "description": "The UUID of the user", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "description": "The full name of the user", "example": "John Doe" }, "email": { "type": "string", "description": "The email address of the user", "example": "john@example.com" }, "phone": { "type": [ "string", "null" ], "description": "The phone number of the user", "example": "+1-555-0100" }, "createdAt": { "type": "string", "format": "date-time", "description": "The ISO 8601 datetime when the user was created", "example": "2024-01-15T12:00:00.000000Z" }, "photoUrl": { "type": "string", "description": "The URL of the user's profile photo", "example": "https://www.gravatar.com/avatar/abc123.jpg?s=200&d=mm" }, "onboarding": { "description": "Onboarding state data for the user" } }, "required": [ "id", "uuid", "name", "email", "createdAt", "photoUrl", "onboarding" ] } }, "required": [ "data" ] } ] }, "examples": { "authenticated": { "value": { "data": { "id": 1, "uuid": "550e8400-e29b-41d4-a716-446655440000", "name": "John Doe", "email": "john@example.com", "phone": null, "createdAt": "2024-01-15T12:00:00.000000Z", "photoUrl": "https://www.gravatar.com/avatar/abc123.jpg?s=200&d=mm", "onboarding": {} } } }, "unauthenticated": { "value": {} } } } } } } } }, "/users/merchants": { "get": { "summary": "Get merchants for current user", "description": "Returns the merchants the current user belongs to, along with their roles on each merchant. NOTE: Response shape differs from GET /merchants — this returns { merchants: [...] } not { data: [...] }.", "operationId": "get-user-merchants", "tags": [ "Users" ], "responses": { "200": { "description": "A successful response returning the merchants the current user belongs to", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchants": { "type": "array", "description": "The list of merchants the user belongs to", "items": { "type": "object", "description": "NOTE: uses camelCase keys as that is the existing API behaviour.", "properties": { "id": { "type": "integer", "description": "The unique identifier for the merchant", "example": 1 }, "name": { "type": "string", "description": "The name of the merchant", "example": "ACME Corp" }, "notes": { "type": [ "string", "null" ], "description": "Notes for the merchant" }, "primaryEmail": { "type": [ "string", "null" ], "description": "The primary email address of the merchant", "example": "contact@acme.com" }, "billingCycle": { "type": [ "string", "null" ], "description": "The billing cycle for the merchant", "example": "monthly" }, "billingCycleDay": { "type": [ "integer", "null" ], "description": "The day of the billing cycle", "example": 1 }, "perItemAdjustment": { "type": [ "number", "null" ], "description": "The per-item adjustment for the merchant", "example": 0 }, "photoUrl": { "type": "string", "description": "The URL of the merchant's photo", "example": "https://www.gravatar.com/avatar/abc123.jpg?s=200&d=mm" }, "enabled": { "type": "boolean", "description": "Whether the merchant is enabled" }, "isOrdersEnabled": { "type": "boolean", "description": "Whether orders are enabled for the merchant" }, "isAmazonShipmentsEnabled": { "type": "boolean", "description": "Whether Amazon shipments are enabled for the merchant" }, "roles": { "type": "array", "description": "The roles the user has on this merchant", "items": { "type": "string", "example": "owner" } } }, "required": [ "id", "name", "photoUrl", "enabled", "isOrdersEnabled", "isAmazonShipmentsEnabled", "roles" ] } } }, "required": [ "merchants" ] }, "examples": { "example": { "value": { "merchants": [ { "id": 1, "name": "ACME Corp", "notes": null, "primaryEmail": "contact@acme.com", "billingCycle": "monthly", "billingCycleDay": null, "perItemAdjustment": 0, "photoUrl": "https://www.gravatar.com/avatar/abc123.jpg?s=200&d=mm", "enabled": true, "isOrdersEnabled": false, "isAmazonShipmentsEnabled": false, "roles": [ "owner" ] } ] } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" } } } }, "/users/api-tokens": { "get": { "summary": "List API tokens", "description": "List all API tokens for the current user. The token value is masked in list responses.", "operationId": "list-api-tokens", "tags": [ "API Tokens" ], "responses": { "200": { "description": "A successful response returning the list of API tokens", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "The list of API tokens", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique UUID identifier for the token", "example": "550e8400-e29b-41d4-a716-446655440000" }, "createdAt": { "type": "string", "format": "date-time", "description": "The ISO 8601 datetime when the token was created", "example": "2024-01-15T12:00:00.000000Z" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the token was last used, or null if never used", "example": null }, "name": { "type": "string", "description": "The name of the token", "example": "My API Token" }, "token": { "type": "string", "description": "The token value, masked with asterisks in list responses", "example": "*********************" } }, "required": [ "id", "createdAt", "name", "token" ] } } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "createdAt": "2024-01-15T12:00:00.000000Z", "lastUsedAt": null, "name": "My API Token", "token": "*********************" } ] } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" } } }, "post": { "summary": "Create an API token", "description": "Create a new API token for the current user. The full token value is only returned on creation.", "operationId": "create-api-token", "tags": [ "API Tokens" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "A name to identify this token", "maxLength": 255, "example": "My API Token" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "A successful response after creating the API token", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique UUID identifier for the token", "example": "550e8400-e29b-41d4-a716-446655440000" }, "createdAt": { "type": "string", "format": "date-time", "description": "The ISO 8601 datetime when the token was created", "example": "2024-01-15T12:00:00.000000Z" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the token was last used, or null if never used", "example": null }, "name": { "type": "string", "description": "The name of the token", "example": "My API Token" }, "token": { "type": "string", "description": "The full token value, only shown on creation", "example": "jtc_abc123xyz456" } }, "required": [ "id", "createdAt", "name", "token" ] } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "createdAt": "2024-01-15T12:00:00.000000Z", "lastUsedAt": null, "name": "My API Token", "token": "jtc_abc123xyz456" } } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/users/api-tokens/{api_token}": { "delete": { "summary": "Delete an API token", "description": "Delete an API token for the current user.", "operationId": "delete-api-token", "tags": [ "API Tokens" ], "parameters": [ { "name": "api_token", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the API token to delete", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "200": { "description": "A successful response after deleting the API token", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" } } } }, "/identifier/{identifier}": { "delete": { "summary": "Delete an inventory item identifier", "description": "Delete an identifier (ASIN, EAN, UPC, FNSKU, GTIN, or CUSTOM) from an inventory item.", "operationId": "delete-inventory-item-identifier", "tags": [ "Inventory" ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the inventory item identifier to delete", "example": 1 } } ], "responses": { "200": { "description": "A successful response after deleting the identifier", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Identifier deleted" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Identifier deleted" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "404": { "$ref": "#/paths/~1orders~1%7Border%7D/get/responses/404" } } } }, "/inventory/batch/delete": { "post": { "summary": "Batch delete inventory items", "description": "Delete multiple inventory items at once.", "operationId": "batch-delete-inventory-items", "tags": [ "Inventory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The inventory items to delete", "minItems": 1, "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the inventory item to delete", "example": 1 } }, "required": [ "id" ] } } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "A successful response after deleting the inventory items", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Items deleted" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Items deleted" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/narrative/permissions": { "get": { "summary": "Get current permissions", "description": "Returns a flat boolean permissions map for the current user. Works for both authenticated and unauthenticated users — unauthenticated users receive false for all permissions.", "operationId": "get-current-permissions", "tags": [ "Narrative" ], "responses": { "200": { "description": "A successful response returning the current user's permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "viewCompanyServicesPrice": { "type": "boolean", "description": "Whether the user can view company service prices" }, "editCompanyService": { "type": "boolean", "description": "Whether the user can edit company services" }, "createOutboundShipments": { "type": "boolean", "description": "Whether the user can create outbound shipments" }, "arrangeTransport": { "type": "boolean", "description": "Whether the user can arrange transport for outbound shipments" }, "addAttachments": { "type": "boolean", "description": "Whether the user can add attachments" }, "registerMerchants": { "type": "boolean", "description": "Whether the user can register merchants" }, "updateShippedInboundShipmentItems": { "type": "boolean", "description": "Whether the user can update items on shipped inbound shipments" }, "updateReceivedInboundShipmentItems": { "type": "boolean", "description": "Whether the user can update items on received inbound shipments" }, "manageBundleConfigurations": { "type": "boolean", "description": "Whether the user can manage bundle configurations" }, "outboundShipmentsMerchantCreateAsDraft": { "type": "boolean", "description": "Whether merchants can create outbound shipments as drafts" } }, "required": [ "viewCompanyServicesPrice", "editCompanyService", "createOutboundShipments", "arrangeTransport", "addAttachments", "registerMerchants", "updateShippedInboundShipmentItems", "updateReceivedInboundShipmentItems", "manageBundleConfigurations", "outboundShipmentsMerchantCreateAsDraft" ] }, "examples": { "authenticated": { "value": { "viewCompanyServicesPrice": true, "editCompanyService": false, "createOutboundShipments": true, "arrangeTransport": false, "addAttachments": true, "registerMerchants": false, "updateShippedInboundShipmentItems": false, "updateReceivedInboundShipmentItems": false, "manageBundleConfigurations": false, "outboundShipmentsMerchantCreateAsDraft": false } }, "unauthenticated": { "value": { "viewCompanyServicesPrice": false, "editCompanyService": false, "createOutboundShipments": false, "arrangeTransport": false, "addAttachments": false, "registerMerchants": false, "updateShippedInboundShipmentItems": false, "updateReceivedInboundShipmentItems": false, "manageBundleConfigurations": false, "outboundShipmentsMerchantCreateAsDraft": false } } } } } } } } }, "/adjustments": { "post": { "summary": "Create an inventory adjustment", "operationId": "create-adjustment", "tags": [ "Adjustments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "item_id": { "type": "integer", "description": "The ID of the inventory item to adjust", "example": 1 }, "warehouse_id": { "type": "integer", "description": "The ID of the warehouse to adjust stock in", "example": 1 }, "reason": { "type": "string", "description": "The reason for the adjustment", "example": "found" }, "quantity": { "type": "integer", "description": "The quantity to adjust (positive or negative, but not zero)", "example": 10 }, "notes": { "type": [ "string", "null" ], "description": "Optional notes for the adjustment" }, "location_uuid": { "type": [ "string", "null" ], "format": "uuid", "description": "The UUID of the specific location within the warehouse to adjust stock in" } }, "required": [ "item_id", "warehouse_id", "reason", "quantity" ] } } } }, "responses": { "200": { "description": "A successful response after creating the adjustment", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Adjustment added" }, "adjustment": { "type": "object", "description": "The created adjustment", "properties": { "uuid": { "type": "string", "description": "The unique identifier for the adjustment", "example": "550e8400-e29b-41d4-a716-446655440000" }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the adjustment was created" }, "reason": { "type": "string", "description": "The reason for the adjustment", "enum": [ "lost", "found", "damaged", "other" ] }, "notes": { "type": [ "string", "null" ], "description": "Optional notes for the adjustment" }, "warehouse_uuid": { "type": "string", "description": "The UUID of the warehouse where the adjustment was made" } }, "required": [ "uuid", "created_at", "reason", "warehouse_uuid" ] } }, "required": [ "message", "adjustment" ] }, "examples": { "example": { "value": { "message": "Adjustment added", "adjustment": { "uuid": "550e8400-e29b-41d4-a716-446655440000", "created_at": "2021-05-20T07:54:15.000000Z", "reason": "lost", "notes": null, "warehouse_uuid": "660e8400-e29b-41d4-a716-446655440001" } } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/users/invitations/merchant": { "post": { "summary": "Invite a user to a merchant", "operationId": "invite-user-to-merchant", "tags": [ "Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address of the user to invite", "example": "user@example.com" }, "role": { "type": "string", "description": "The role to assign to the invited user", "example": "merchant_user" }, "merchant_id": { "type": "integer", "description": "The ID of the merchant to invite the user to", "example": 1 } }, "required": [ "email", "role", "merchant_id" ] } } } }, "responses": { "200": { "description": "A successful response after sending the invitation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An invitation to join this merchant has been sent." } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "An invitation to join this merchant has been sent." } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/labels/fnsku": { "post": { "summary": "Request FNSKU labels", "operationId": "request-fnsku-labels", "description": "Submits a request to generate FNSKU labels. Labels are generated asynchronously and will be available for download once processing is complete.", "tags": [ "Labels" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "labels": { "type": "array", "description": "An array of label requests to generate", "minItems": 1, "items": { "type": "object", "properties": { "fnsku": { "type": "string", "description": "The 10-character Amazon FNSKU code", "minLength": 10, "maxLength": 10, "example": "X00SPO3LCY" }, "condition": { "type": "string", "description": "The condition of the item", "enum": [ "new", "new_oem", "new_with_warranty", "new_open_box", "used_like_new", "used_very_good", "used_good", "used_acceptable", "used_poor", "collectible_like_new", "collectible_very_good", "collectible_good", "collectible_acceptable", "collectible_poor", "used_refurbished", "refurbished" ], "example": "new" }, "title": { "type": "string", "description": "The product title to print on the label", "example": "Mini Portable Charger" }, "count": { "type": "integer", "description": "The number of labels to generate for this item", "minimum": 1, "example": 10 }, "expiry_date": { "type": [ "string", "null" ], "format": "date", "description": "Optional expiry date to print on the label (YYYY-MM-DD). Only applicable when expiry date printing is enabled for your account.", "example": "2026-12-31" } }, "required": [ "fnsku", "condition", "title", "count" ] } } }, "required": [ "labels" ] }, "examples": { "example": { "value": { "labels": [ { "fnsku": "X00SPO3LCY", "condition": "new", "title": "Mini Portable Charger", "count": 10, "expiry_date": null }, { "fnsku": "X001AB2CD3", "condition": "used_like_new", "title": "Wireless Mouse", "count": 5, "expiry_date": "2026-12-31" } ] } } } } } }, "responses": { "200": { "description": "Labels have been successfully queued for generation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Labels requested" }, "reference_uuid": { "type": "string", "format": "uuid", "description": "A reference ID for this label generation request. Use this to filter GET /api/printing/jobs to retrieve the generated print job and its download URL once processing is complete.", "example": "01950d63-b2f7-7000-9f3e-4c2a1b0e8d5f" } }, "required": [ "message", "reference_uuid" ] }, "examples": { "example": { "value": { "message": "Labels requested", "reference_uuid": "01950d63-b2f7-7000-9f3e-4c2a1b0e8d5f" } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" }, "422": { "$ref": "#/paths/~1inventory/post/responses/422" } } } }, "/printing/jobs": { "get": { "summary": "List print jobs", "operationId": "index-print-jobs", "description": "Returns a paginated list of print jobs for the authenticated user. Use the `q` parameter with search language syntax to filter by `reference_uuid` (e.g. `reference_uuid:\"01950d63-b2f7-7000-9f3e-4c2a1b0e8d5f\"`) to retrieve the print job created for a specific FNSKU label request.", "tags": [ "Printing" ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search language filter. Supported fields: `reference_uuid` (uuid). Example: `reference_uuid:\"01950d63-b2f7-7000-9f3e-4c2a1b0e8d5f\"`", "example": "reference_uuid:\"01950d63-b2f7-7000-9f3e-4c2a1b0e8d5f\"" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } } ], "responses": { "200": { "description": "A paginated list of print jobs", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/paths/~1inventory/get/responses/200/content/application~1json/schema/allOf/0" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "01950d63-b2f7-7000-9f3e-4c2a1b0e8d5f" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-01-15T10:30:00+00:00" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-01-15T10:30:05+00:00" }, "status": { "type": "string", "enum": [ "waiting", "completed", "cancelled" ], "example": "completed" }, "name": { "type": "string", "example": "FNSKU Labels (10)" }, "source": { "type": "string", "example": "api" }, "reference_uuid": { "type": [ "string", "null" ], "format": "uuid", "description": "The reference UUID from the original label generation request, if provided.", "example": "01950d63-b2f7-7000-9f3e-4c2a1b0e8d5f" }, "printer": { "type": "object", "properties": { "identifier": { "type": "string", "example": "printer-001" }, "brand": { "type": "string", "example": "Zebra" }, "density": { "type": "integer", "example": 203 } }, "required": [ "identifier", "brand", "density" ] }, "document": { "type": "object", "description": "The generated document. The `url` field contains the download link for the label file.", "properties": { "url": { "type": "string", "format": "uri", "description": "URL to download the generated label file.", "example": "https://app.prepbusiness.com/storage/labels/01950d63.pdf" }, "width_mm": { "type": "integer", "example": 38 }, "height_mm": { "type": "integer", "example": 25 }, "type": { "type": "string", "enum": [ "pdf", "zpl", "epl" ], "example": "pdf" } }, "required": [ "url", "width_mm", "height_mm", "type" ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event": { "type": "string", "enum": [ "print_job_attempted", "print_job_cancelled", "print_job_completed", "print_job_failed" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "data": { "type": "object" } }, "required": [ "id", "event", "occurred_at", "data" ] } } }, "required": [ "id", "created_at", "updated_at", "status", "name", "source", "reference_uuid", "printer", "document", "events" ] } } } } ] }, "examples": { "example": { "value": { "data": [ { "id": "01950d63-b2f7-7000-9f3e-4c2a1b0e8d5f", "created_at": "2026-01-15T10:30:00+00:00", "updated_at": "2026-01-15T10:30:05+00:00", "status": "completed", "name": "FNSKU Labels (10)", "source": "api", "reference_uuid": "01950d63-b2f7-7000-9f3e-4c2a1b0e8d5f", "printer": { "identifier": "printer-001", "brand": "Zebra", "density": 203 }, "document": { "url": "https://app.prepbusiness.com/storage/labels/01950d63.pdf", "width_mm": 38, "height_mm": 25, "type": "pdf" }, "events": [ { "id": "01950d63-c3a8-8000-af4f-5d3b2c1f9e6a", "event": "print_job_completed", "occurred_at": "2026-01-15T10:30:05+00:00", "data": {} } ] } ], "total": 1, "current_page": 1, "last_page": 1, "per_page": 10, "from": 1, "to": 1 } } } } } }, "401": { "$ref": "#/paths/~1orders/get/responses/401" }, "403": { "$ref": "#/paths/~1orders/get/responses/403" } } } } }, "tags": [ { "name": "Channels", "description": "Viewing and managing channels and listings" }, { "name": "Billing", "description": "Viewing and managing charges and invoices" }, { "name": "Inventory", "description": "Viewing and managing inventory items" }, { "name": "Inbound Shipments", "description": "Viewing and managing inbound shipments and their items" }, { "name": "Outbound Shipments", "description": "Viewing and managing outbound shipments and their items" }, { "name": "FBA Transport", "description": "Viewing and managing FBA transport plans" }, { "name": "Orders", "description": "Viewing and managing orders" }, { "name": "Services", "description": "Viewing and managing company services" }, { "name": "Warehouses", "description": "Viewing and managing warehouses" }, { "name": "Merchants", "description": "Viewing and managing merchants" }, { "name": "Adjustments", "description": "Creating inventory adjustments" }, { "name": "Users", "description": "Viewing and managing user invitations" }, { "name": "Labels", "description": "Generating and downloading FNSKU and barcode labels" }, { "name": "Printing", "description": "Viewing and managing print jobs" }, { "name": "API Tokens", "description": "Managing API tokens for authentication" }, { "name": "Narrative", "description": "Context-aware permission checks" } ], "components": { "schemas": {}, "securitySchemes": { "default": { "type": "http", "scheme": "bearer", "description": "Your API token can be found or created from the API section of your dashboard.\n\nTo use the token, add the following header to your request:\n\n```\nAuthorization: Bearer YOUR_API_TOKEN\n```" } } }, "security": [ { "default": [] } ] }