{ "openapi": "3.1.0", "info": { "title": "API", "description": "API", "version": "1.0.0", "contact": { "name": "Support", "email": "support@prepbusiness.com", "url": "https://prepbusiness.com" } }, "servers": [ { "url": "https://{host}/api", "description": "Your PrepBusiness instance. The API is served from the same origin as your web app — there is no central API host, so substitute your own instance domain.", "variables": { "host": { "default": "your-instance.example.com", "description": "The domain of your PrepBusiness instance." } } } ], "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": { "$ref": "#/components/schemas/Channel" } } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } } }, "/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": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Listing" } } }, "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" }, "channel_type": "amazon", "amazon": { "fnsku": "X0012345", "catalog_item": null }, "walmart": null } ], "total": 2, "current_page": 1, "last_page": 1, "per_page": 20, "from": 1, "to": 2 } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } }, "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", "null" ], "description": "The ID of the inventory item to link to this listing. If omitted, the listing is created without a linked item.", "example": 1 }, "merchant_sku": { "type": [ "string", "null" ], "description": "The merchant SKU to use for this listing. If omitted, the item's SKU is used, falling back to the channel identifier when there is no linked item." }, "condition": { "type": [ "string", "null" ], "maxLength": 255, "description": "Accepted for compatibility and not stored. Walmart conditions are set when the listing is pushed to Walmart." } }, "required": [ "channel_identifier" ] } } } }, "responses": { "201": { "description": "A successful response returning the created listing", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Listing" } }, "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, "channel_type": "amazon", "amazon": { "fnsku": null, "catalog_item": null }, "walmart": null } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/channels/amazon/connection-invitation": { "post": { "summary": "Create an Amazon channel connection invitation", "operationId": "create-amazon-channel-connection-invitation", "tags": [ "Channels" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "marketplace": { "type": "string", "description": "The Amazon marketplace identifier to connect", "example": "ATVPDKIKX0DER" }, "nickname": { "type": [ "string", "null" ], "description": "An optional nickname for the channel" }, "redirect_url": { "type": "string", "format": "uri", "description": "The URL to redirect the merchant to after they successfully connect their Amazon channel", "example": "https://app.example.com/channels/connected" } }, "required": [ "marketplace", "redirect_url" ] } } } }, "responses": { "200": { "description": "A successful response returning the invitation token, expiry, and connection URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The short-lived token the merchant uses to connect their Amazon channel", "example": "550e8400-e29b-41d4-a716-446655440000" }, "expires_at": { "type": "string", "format": "date-time", "description": "The UTC datetime when the invitation token expires (24 hours from creation)", "example": "2026-06-16T12:00:00+00:00" }, "connection_url": { "type": "string", "format": "uri", "description": "The URL to direct the merchant to in order to connect their Amazon channel. Visiting it validates the invitation token and forwards the merchant to Amazon OAuth.", "example": "https://acme.conveyr.com/external-oauth/amazon/channel-connection/550e8400-e29b-41d4-a716-446655440000" } }, "required": [ "token", "expires_at", "connection_url" ] }, "examples": { "example": { "value": { "token": "550e8400-e29b-41d4-a716-446655440000", "expires_at": "2026-06-16T12:00:00+00:00", "connection_url": "https://acme.conveyr.com/external-oauth/amazon/channel-connection/550e8400-e29b-41d4-a716-446655440000" } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/channels/amazon/{channel}/listing-restrictions": { "get": { "summary": "Index stored listing restrictions", "operationId": "index-channel-amazon-listing-restrictions", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the Amazon channel", "example": 1 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search language filter. Supported fields: `asin`, `marketplace_id`, and `condition_type`.", "example": "asin:\"B00ZB18SIF\"" }, { "name": "page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Page" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PerPage" } } ], "responses": { "200": { "description": "A successful response returning a paginated list of stored listing restriction records", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListingRestriction" } } }, "required": [ "data" ] } ] }, "examples": { "example": { "value": { "data": [ { "id": "019b2286-9fee-71de-9f64-154824d3aa4d", "channel_id": 1, "asin": "B00ZB18SIF", "marketplace_id": "ATVPDKIKX0DER", "condition_type": "new_new", "restrictions": [ { "marketplace_id": "ATVPDKIKX0DER", "condition_type": "new_new", "reasons": [ { "reason_code": "APPROVAL_REQUIRED", "message": "Approval is required to list this item.", "links": [ { "resource": "https://sellercentral.amazon.com/hz/approvalrequest/restrictions/approve", "verb": "GET", "title": "Request approval" } ] } ] } ] } ], "total": 1, "current_page": 1, "last_page": 1, "per_page": 10, "from": 1, "to": 1 } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/channels/amazon/{channel}/fetch-listing-restrictions": { "get": { "summary": "Fetch listing restrictions from Amazon", "operationId": "fetch-channel-amazon-listing-restrictions-from-amazon", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the Amazon channel", "example": 1 } }, { "name": "asin", "in": "query", "required": true, "schema": { "type": "string", "example": "B00ZB18SIF" } }, { "name": "condition_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "new_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_new" } } ], "responses": { "200": { "description": "A successful response returning the fetched listing restriction record", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/ListingRestriction" }, { "type": "null" } ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/channels/{channel}": { "get": { "summary": "Show a channel", "description": "Get a single channel by its ID. Used to populate the channel edit page.", "operationId": "show-channel", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the channel", "example": 1 } } ], "responses": { "200": { "description": "A successful response returning the channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "$ref": "#/components/schemas/Channel" } }, "required": [ "channel" ] }, "examples": { "example": { "value": { "channel": { "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", "created_at": "2026-06-16T12:00:00.000000+00:00", "updated_at": "2026-06-16T12:00:00.000000+00:00" } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } } }, "delete": { "summary": "Delete a channel", "description": "Delete a channel and its associated listings, listing-product links, and Amazon feeds.", "operationId": "delete-channel", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the channel", "example": 1 } } ], "responses": { "200": { "description": "A successful response after deleting the channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Channel deleted" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Channel deleted" } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } } } }, "/channels/{channel}/activate": { "get": { "summary": "Activate a channel", "description": "Mark a channel as active. Used on the channel edit page.", "operationId": "activate-channel", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the channel", "example": 1 } } ], "responses": { "200": { "description": "A successful response after activating the channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Channel activated" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Channel activated" } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } } } }, "/channels/{channel}/deactivate": { "get": { "summary": "Deactivate a channel", "description": "Deactivate a channel, setting its connection status to `unauthorized`. Used on the channel edit page.", "operationId": "deactivate-channel", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the channel", "example": 1 } } ], "responses": { "200": { "description": "A successful response after deactivating the channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Channel deactivated" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Channel deactivated" } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } } } }, "/channels/amazon": { "post": { "summary": "Create an Amazon channel", "description": "Create a new Amazon channel for the current merchant. The channel is created in an unauthorized state; use the authorize-url endpoint to begin the OAuth flow.", "operationId": "create-amazon-channel", "tags": [ "Channels" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "marketplace": { "type": "string", "description": "The Amazon marketplace identifier to connect", "example": "ATVPDKIKX0DER" }, "nickname": { "type": "string", "description": "An optional nickname for the channel", "maxLength": 255, "example": "Amazon Store" } }, "required": [ "marketplace" ] } } } }, "responses": { "200": { "description": "A successful response returning the created channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Channel created" }, "channel": { "$ref": "#/components/schemas/Channel" } }, "required": [ "message", "channel" ] }, "examples": { "example": { "value": { "message": "Channel created", "channel": { "id": 2, "merchant_id": 2, "team_id": 2, "type": "amazon", "nickname": "Amazon Store", "channel_account_id": null, "connection_status": "unauthorized", "country_id": "ATVPDKIKX0DER", "created_at": "2026-06-16T12:00:00.000000+00:00", "updated_at": "2026-06-16T12:00:00.000000+00:00" } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/channels/amazon/{channel}": { "put": { "summary": "Update an Amazon channel", "description": "Update an Amazon channel's nickname and marketplace. Changing the marketplace disconnects the channel and sets its connection status to `unauthorized`, requiring re-authorization.", "operationId": "update-amazon-channel", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the Amazon channel", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "marketplace": { "type": "string", "description": "The Amazon marketplace identifier", "example": "ATVPDKIKX0DER" }, "nickname": { "type": [ "string", "null" ], "description": "An optional nickname for the channel", "maxLength": 255, "example": "Amazon Store" } }, "required": [ "marketplace" ] } } } }, "responses": { "200": { "description": "A successful response after updating the channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Channel updated" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Channel updated" } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/channels/amazon/{channel}/authorize-url": { "get": { "summary": "Get the Amazon channel authorize URL", "description": "Return the Amazon OAuth URL to redirect the merchant to in order to authorize the channel. This is the real \"authorize\" step of connecting an Amazon channel.", "operationId": "get-amazon-channel-authorize-url", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the Amazon channel", "example": 1 } } ], "responses": { "200": { "description": "A successful response returning the OAuth URL to redirect to", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The Amazon OAuth URL to redirect the merchant to", "example": "https://sellercentral.amazon.com/apps/authorize/consent?application_id=amzn1.sp.solution.abc&state=xyz" } }, "required": [ "url" ] }, "examples": { "example": { "value": { "url": "https://sellercentral.amazon.com/apps/authorize/consent?application_id=amzn1.sp.solution.abc&state=xyz" } } } } } }, "400": { "description": "The channel is not an Amazon channel or is not configured with a marketplace", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Channel type is not Amazon" } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } } } }, "/channels/amazon/marketplaces": { "get": { "summary": "List Amazon marketplaces", "description": "Return the list of Amazon marketplaces that a channel can be connected to.", "operationId": "index-amazon-marketplaces", "tags": [ "Channels" ], "responses": { "200": { "description": "A successful response returning the list of Amazon marketplaces", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "identifier": { "type": "string", "description": "The Amazon marketplace identifier", "example": "ATVPDKIKX0DER" }, "country": { "type": "string", "description": "The human-readable country name for the marketplace", "example": "United States" } }, "required": [ "identifier", "country" ] } }, "examples": { "example": { "value": [ { "identifier": "ATVPDKIKX0DER", "country": "United States" }, { "identifier": "A2EUQ1WTGCTBG2", "country": "Canada" } ] } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } } }, "/channels/amazon/catalog-items/{catalog_item_uuid}/prices": { "get": { "summary": "Show a Amazon catalog item's landed-price analytics", "description": "Summarises daily UTC landed-price observations of the Amazon New featured offer for one Amazon catalog item into calendar buckets over [start, end). Catalog prices are global per platform, so no listing, channel or merchant link is needed; the caller needs listings:view on the narrated account. A uuid that is not an existing Amazon catalog item returns 404. Days are UTC calendar days, weeks start on Monday and months on the first. Edge buckets are clipped to the range. Each observed currency is its own series; an item with no observations in the range returns an empty series array. Averages are per observation, not time-weighted, and the current UTC day may still gain observations.", "operationId": "show-amazon-catalog-item-prices", "tags": [ "Channels" ], "parameters": [ { "name": "catalog_item_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The Amazon catalog item's uuid", "example": "019b2286-9fee-8019-9f64-154824d3aa4d" } }, { "name": "start", "in": "query", "required": true, "description": "First UTC day to include, as YYYY-MM-DD with a four-digit AD year from 0001 to 9999.", "schema": { "type": "string", "format": "date", "example": "2026-09-28" } }, { "name": "end", "in": "query", "required": true, "description": "UTC day after the last day to include, as YYYY-MM-DD with a four-digit AD year from 0001 to 9999. Must be after start, at most 731 days later.", "schema": { "type": "string", "format": "date", "example": "2026-10-03" } }, { "name": "granularity", "in": "query", "required": true, "description": "Bucket size: UTC calendar day, Monday-start week, or calendar month.", "schema": { "type": "string", "enum": [ "day", "week", "month" ], "example": "week" } } ], "responses": { "200": { "description": "Landed-price buckets per observed currency.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogItemPriceAnalytics" }, "examples": { "weekly": { "value": { "start": "2026-09-28", "end": "2026-10-03", "granularity": "week", "timezone": "UTC", "series": [ { "currency": "USD", "buckets": [ { "start": "2026-09-28", "end": "2026-10-03", "lowest_landed_price": "19.9900", "highest_landed_price": "21.0000", "average_landed_price": "20.3267", "observation_count": 3, "observed_days": 2 } ] } ] } }, "daily_with_gap": { "value": { "start": "2026-09-30", "end": "2026-10-02", "granularity": "day", "timezone": "UTC", "series": [ { "currency": "USD", "buckets": [ { "start": "2026-09-30", "end": "2026-10-01", "lowest_landed_price": "19.9900", "highest_landed_price": "19.9900", "average_landed_price": "19.9900", "observation_count": 1, "observed_days": 1 }, { "start": "2026-10-01", "end": "2026-10-02", "lowest_landed_price": null, "highest_landed_price": null, "average_landed_price": null, "observation_count": 0, "observed_days": 0 } ] } ] } }, "no_observations": { "value": { "start": "2026-09-01", "end": "2026-10-01", "granularity": "month", "timezone": "UTC", "series": [] } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/channels/amazon/{channel}/inventory-levels": { "get": { "summary": "Index an Amazon channel's listing inventory levels", "description": "Returns one entry per stored AFN or MFN level, so one listing can have two entries. Listings without inventory are omitted and `total` counts levels. Values are retained until replaced: `synced_at` is the source-request time and exposes staleness, while nullable `reported_at` is a legacy vendor timestamp and is not freshness. AFN and MFN may have different ages. This read-only request does not fetch Amazon, inactive channels remain readable, and replica reads may lag recent writes slightly.", "operationId": "index-amazon-inventory-levels", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the Amazon channel", "example": 1 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search language filter for `listing_id`, `sku`, and `fulfillment_network`. Clauses can be combined with `AND` or `OR`; fragments the search-language parser does not recognize are ignored, while recognized clauses must use a supported field and valid value. Unknown network values simply return no rows. Example: `sku~\"WIDGET\" AND fulfillment_network:\"afn\"`", "example": "sku~\"WIDGET\" AND fulfillment_network:\"afn\"" }, { "name": "sorts", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "type": "array", "maxItems": 2, "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "enum": [ "sku", "synced_at" ] }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "order": { "type": "integer", "minimum": 1 } }, "required": [ "field", "order" ] } }, "description": "Up to two requested sorts. Defaults to listing_id ascending then fulfillment_network ascending. Requested priorities are normalized and those same tie-breakers are appended, keeping page boundaries stable even for equal SKU or synced_at values. Example: `sorts[0][field]=synced_at&sorts[0][direction]=desc&sorts[0][order]=1`." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "example": 25 } } ], "responses": { "200": { "description": "A paginated list of stored inventory levels; total counts AFN/MFN level rows", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "One stored Amazon inventory level for one listing and fulfillment network. AFN and MFN are separate rows and may have different ages. Quantities are not summed. `reported_at` is Amazon's optional legacy observation time and is not freshness; `synced_at` is when the source request was made.", "additionalProperties": false, "properties": { "listing_id": { "type": "integer", "description": "The listing ID", "example": 21 }, "sku": { "type": "string", "description": "The listing SKU", "example": "SD-AB-12345" }, "fulfillment_network": { "type": "string", "enum": [ "afn", "mfn" ], "description": "Amazon-fulfilled (afn) or merchant-fulfilled (mfn)", "example": "afn" }, "quantity": { "type": "integer", "description": "The quantity for this fulfillment network", "example": 12 }, "total_quantity": { "type": [ "integer", "null" ], "description": "Amazon's total quantity for this level, not a total across AFN and MFN; null when unavailable", "example": 20 }, "inbound_working_quantity": { "type": [ "integer", "null" ], "description": "Inbound working quantity; null when unavailable", "example": 2 }, "inbound_shipped_quantity": { "type": [ "integer", "null" ], "description": "Inbound shipped quantity; null when unavailable", "example": 3 }, "inbound_receiving_quantity": { "type": [ "integer", "null" ], "description": "Inbound receiving quantity; null when unavailable", "example": 4 }, "reserved_quantity": { "type": [ "integer", "null" ], "description": "Reserved quantity; null when unavailable", "example": 5 }, "researching_quantity": { "type": [ "integer", "null" ], "description": "Researching quantity; null when unavailable", "example": 6 }, "unfulfillable_quantity": { "type": [ "integer", "null" ], "description": "Unfulfillable quantity; null when unavailable", "example": 7 }, "reported_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Legacy vendor observation timestamp when present; null for report-written rows and never replaced with synced_at", "example": "2026-09-01T04:05:12Z" }, "synced_at": { "type": "string", "format": "date-time", "description": "When the source request that returned this level was made; stale values are retained unchanged", "example": "2026-10-01T04:05:12Z" } }, "required": [ "listing_id", "sku", "fulfillment_network", "quantity", "total_quantity", "inbound_working_quantity", "inbound_shipped_quantity", "inbound_receiving_quantity", "reserved_quantity", "researching_quantity", "unfulfillable_quantity", "reported_at", "synced_at" ] } } }, "required": [ "data" ] } ] }, "examples": { "levels": { "value": { "data": [ { "listing_id": 21, "sku": "SD-AB-12345", "fulfillment_network": "afn", "quantity": 12, "total_quantity": 20, "inbound_working_quantity": 2, "inbound_shipped_quantity": 3, "inbound_receiving_quantity": 4, "reserved_quantity": 5, "researching_quantity": 6, "unfulfillable_quantity": 7, "reported_at": "2026-09-01T04:05:12Z", "synced_at": "2026-10-01T04:05:12Z" }, { "listing_id": 21, "sku": "SD-AB-12345", "fulfillment_network": "mfn", "quantity": 0, "total_quantity": null, "inbound_working_quantity": null, "inbound_shipped_quantity": null, "inbound_receiving_quantity": null, "reserved_quantity": null, "researching_quantity": null, "unfulfillable_quantity": null, "reported_at": null, "synced_at": "2026-10-02T04:05:12Z" } ], "total": 2, "current_page": 1, "last_page": 1, "per_page": 10, "from": 1, "to": 2 } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/channels/custom": { "post": { "summary": "Create a custom channel", "description": "Create a new custom channel for the current merchant. Custom channels are created in an active state.", "operationId": "create-custom-channel", "tags": [ "Channels" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nickname": { "type": "string", "description": "A nickname for the channel", "maxLength": 255, "example": "My Custom Channel" } }, "required": [ "nickname" ] } } } }, "responses": { "200": { "description": "A successful response returning the created channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Channel created" }, "channel": { "$ref": "#/components/schemas/Channel" } }, "required": [ "message", "channel" ] }, "examples": { "example": { "value": { "message": "Channel created", "channel": { "id": 3, "merchant_id": 2, "team_id": 2, "type": "custom", "nickname": "My Custom Channel", "connection_status": "active", "created_at": "2026-06-16T12:00:00.000000+00:00", "updated_at": "2026-06-16T12:00:00.000000+00:00" } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/channels/custom/{channel}": { "put": { "summary": "Update a custom channel", "description": "Update a custom channel's nickname.", "operationId": "update-custom-channel", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the custom channel", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nickname": { "type": "string", "description": "A nickname for the channel", "maxLength": 255, "example": "My Custom Channel" } }, "required": [ "nickname" ] } } } }, "responses": { "200": { "description": "A successful response after updating the channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Channel updated" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Channel updated" } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/channels/walmart": { "post": { "summary": "Create a Walmart channel", "description": "Create a new Walmart channel for the current merchant. The channel is created in an unauthorized state; use the authorize-url endpoint to begin the OAuth flow.", "operationId": "create-walmart-channel", "tags": [ "Channels" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "marketplace": { "type": "string", "description": "The Walmart marketplace to connect", "enum": [ "us", "ca", "mx" ], "example": "us" }, "nickname": { "type": "string", "description": "An optional nickname for the channel", "maxLength": 255, "example": "Walmart Store" } }, "required": [ "marketplace" ] } } } }, "responses": { "200": { "description": "A successful response returning the created channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Channel created" }, "channel": { "$ref": "#/components/schemas/Channel" } }, "required": [ "message", "channel" ] }, "examples": { "example": { "value": { "message": "Channel created", "channel": { "id": 2, "merchant_id": 2, "team_id": 2, "type": "walmart", "nickname": "Walmart Store", "channel_account_id": "pending", "connection_status": "unauthorized", "marketplace": "us", "created_at": "2026-06-16T12:00:00.000000+00:00", "updated_at": "2026-06-16T12:00:00.000000+00:00" } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/channels/walmart/{channel}/authorize-url": { "get": { "summary": "Get the Walmart channel authorize URL", "description": "Return the Walmart OAuth URL to redirect the merchant to in order to authorize the channel. This is the real \"authorize\" step of connecting a Walmart channel.", "operationId": "get-walmart-channel-authorize-url", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the Walmart channel", "example": 1 } }, { "name": "walmart_callback_uri", "in": "query", "required": false, "schema": { "type": "string", "format": "uri", "description": "The Walmart authorization endpoint to redirect to, as handed to us by the App Store-initiated connect flow. Must be an allow-listed Walmart host.", "example": "https://login.account.wal-mart.com/authorize" } } ], "responses": { "200": { "description": "A successful response returning the OAuth URL to redirect to", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The Walmart OAuth URL to redirect the merchant to", "example": "https://login.account.wal-mart.com/authorize?responseType=code&clientId=abc&state=xyz" } }, "required": [ "url" ] }, "examples": { "example": { "value": { "url": "https://login.account.wal-mart.com/authorize?responseType=code&clientId=abc&state=xyz" } } } } } }, "400": { "description": "The channel is not a Walmart channel or is not configured with a marketplace", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Channel type is not Walmart" } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/channels/walmart/{channel}/feeds": { "get": { "summary": "Index a Walmart channel's feeds", "description": "The feeds submitted to Walmart for this channel, newest first, with their processing status.", "operationId": "index-walmart-feeds", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the Walmart channel", "example": 1 } }, { "name": "feed_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "OMNI_WFS", "MP_ITEM_MATCH", "MP_MAINTENANCE", "PRICE_AND_PROMOTION" ] }, "description": "Only feeds of this type" }, { "name": "page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Page" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PerPage" } } ], "responses": { "200": { "description": "A paginated list of feeds", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WalmartFeed" } } }, "required": [ "data" ] } ] }, "examples": { "example": { "value": { "data": [ { "uuid": "019b2286-9fee-71de-9f64-154824d3aa4d", "feed_type": "MP_ITEM_MATCH", "status": "processed", "walmart_feed_id": "F129C19240844B97A3C6AD8F1A2C4997@AU8BAQA", "items_received": 1, "items_succeeded": 1, "items_failed": 0, "items_processing": 0, "errors": [], "submitted_at": "2026-09-28T15:00:05Z", "processed_at": "2026-09-28T15:04:40Z", "failed_at": null, "created_at": "2026-09-28T15:00:00Z" } ], "total": 1, "current_page": 1, "last_page": 1, "per_page": 10, "from": 1, "to": 1 } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/channels/walmart/{channel}/inventory-levels": { "get": { "summary": "Index a Walmart channel's listing inventory levels", "description": "One entry per listing of the channel, with the last WFS and ship-node levels stored for it. Listings with no stored level are included with `wfs: null` and an empty `ship_nodes`; missing levels are not zero. Every quantity Walmart did not report is null, and zero is only returned when Walmart reported zero. WFS and ship-node levels are synced from separate Walmart requests, so each carries its own `synced_at` (the time of that request) and they can be of different ages. Levels are retained until a later sync replaces them, so an old `synced_at` means the level may no longer be current; the levels are not a guarantee of current stock or a complete catalogue. WFS and ship-node quantities may describe the same units and must not be added together. Nothing is fetched from Walmart by this request. Reads may lag recent writes slightly. Inactive channels remain readable.", "operationId": "index-walmart-inventory-levels", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the Walmart channel", "example": 1 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search language filter. Supported fields: `listing_id` (integer; `:`, `!:`, `>`, `>=`, `<`, `<=`) and `sku` (string; `:`, `!:`, `~`, `!~`). Substring matches require at least 3 characters. Clauses can be combined with `AND` / `OR`. Any other field or operator is rejected with a 422. Example: `sku~\"WIDGET\" AND listing_id>\"100\"`", "example": "sku~\"WIDGET\" AND listing_id>\"100\"" }, { "name": "sorts", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "type": "array", "maxItems": 2, "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "listing_id", "sku" ], "description": "The field to sort by" }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "The sort direction. Defaults to asc." }, "order": { "type": "integer", "minimum": 1, "description": "The position of this sort relative to the others" } }, "required": [ "field", "order" ] } }, "description": "Sort the results. Defaults to `listing_id` ascending; unless `listing_id` is sorted explicitly, `listing_id` ascending is applied last so listings with the same SKU keep a stable order. Example: `sorts[0][field]=sku&sorts[0][direction]=desc&sorts[0][order]=1`" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "The page number to retrieve (1-indexed)", "minimum": 1, "default": 1, "example": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "The number of listings per page", "minimum": 1, "maximum": 100, "default": 10, "example": 25 } } ], "responses": { "200": { "description": "A paginated list of the channel's listings with their stored inventory levels; `total` counts listings, not ship nodes", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WalmartListingInventoryLevel" } } }, "required": [ "data" ] } ] }, "examples": { "example": { "value": { "data": [ { "listing_id": 21, "sku": "SD-AB-12345", "wfs": { "available_units": 120, "reserved_units": 4, "inbound_units": 0, "on_hand_units": 130, "unavailable_units": 6, "stock_status": "IN_STOCK", "synced_at": "2026-10-07T04:05:12Z" }, "ship_nodes": [ { "ship_node": "0701234567", "available_to_sell_quantity": 15, "input_quantity": 18, "reserved_quantity": null, "synced_at": "2026-10-07T04:06:40Z" } ] }, { "listing_id": 22, "sku": "SD-AB-67890", "wfs": null, "ship_nodes": [] } ], "total": 2, "current_page": 1, "last_page": 1, "per_page": 10, "from": 1, "to": 2 } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/channels/walmart/{channel}/inventory-levels/{listing}/refresh": { "post": { "summary": "Refresh a Walmart listing's stored inventory levels", "description": "Requires listings:update. Fetches fresh WFS inventory and inventory across all ship nodes for the listing's Walmart SKU (channel_identifier), then saves the reported levels together and returns the stored values. Both Walmart lookups must succeed before either source is saved. An inactive or disconnected channel is rejected. Quantities Walmart omits remain null; zero is stored only when Walmart reports zero. Previously stored WFS or ship-node levels omitted from a successful response are retained with their original synced_at. Newer stored observations are not overwritten. Each source carries the time its lookup began. WFS and ship-node quantities may describe the same units and must not be added together. The response is read from the primary database.", "operationId": "refresh-walmart-inventory-levels", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the Walmart channel" } }, { "name": "listing", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of a listing belonging to this channel" } } ], "responses": { "200": { "description": "The listing with its stored WFS and ship-node levels after the refresh", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WalmartListingInventoryLevel" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "description": "The channel is inactive or has not completed OAuth", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "502": { "description": "Walmart failed to return valid inventory for this SKU; stored levels remain unchanged", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/channels/walmart/{channel}/listings/{listing}/price/refresh": { "post": { "summary": "Refresh a Walmart listing's stored seller price", "description": "Requires listings:update. Fetches the item for the listing's Walmart SKU (channel_identifier) and saves its reported price and item facts. Returns the stored price from the primary database. The price is the seller's own offer price. An inactive or disconnected channel is rejected. Empty responses and missing or unparseable prices retain the previous observation, including synced_at; without stored details, price and synced_at are null. Zero is stored only when Walmart reports zero. Newer stored details are not overwritten. synced_at is the time the lookup began. Catalogue links and WFS enrolment are preserved.", "operationId": "refresh-walmart-listing-price", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the Walmart channel" } }, { "name": "listing", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of a listing belonging to this channel" } } ], "responses": { "200": { "description": "The listing's stored price after the refresh", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "listing_id": { "type": "integer" }, "sku": { "type": "string", "description": "The local listing SKU" }, "price": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "A decimal amount with four fractional digits" }, "currency": { "type": "string", "description": "The ISO 4217 currency code" } }, "required": [ "amount", "currency" ] }, "synced_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "listing_id", "sku", "price", "synced_at" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "description": "The channel is inactive or has not completed OAuth", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "502": { "description": "Walmart failed to return valid item details for this SKU; the stored price remains unchanged", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/channels/walmart/{channel}/taxonomy": { "get": { "summary": "List Walmart product types", "description": "Walmart's product type taxonomy for a feed type, flattened to one row per product type, for a product type picker. Read from Walmart's `GET /v3/items/taxonomy` (https://developer.walmart.com/us-marketplace/reference/gettaxonomyresponse) and cached for 24 hours per marketplace and feed type. For an existing Walmart item, the product type it is listed under is authoritative; see `walmart.live_item.product_type` on the listing.", "operationId": "index-walmart-taxonomy", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the Walmart channel", "example": 1 } }, { "name": "feed_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "MP_ITEM", "MP_WFS_ITEM", "MP_MAINTENANCE" ] }, "description": "The item spec feed type whose taxonomy to return" } ], "responses": { "200": { "description": "The product types", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "example": "Beauty" }, "product_type_group": { "type": "string", "example": "Fragrances" }, "product_type": { "type": "string", "example": "Body Sprays" } }, "additionalProperties": false, "required": [ "category", "product_type_group", "product_type" ] } } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": [ { "category": "Beauty", "product_type_group": "Fragrances", "product_type": "Body Sprays" } ] } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" }, "502": { "description": "Walmart did not return its taxonomy", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Walmart did not return its taxonomy. Try again later." } }, "required": [ "message" ] } } } } } } }, "/channels/walmart/feeds/{walmart_feed}": { "get": { "summary": "Show a Walmart feed", "description": "One feed with Walmart's result for each item in it. Items are empty until the feed is processed.", "operationId": "show-walmart-feed", "tags": [ "Channels" ], "parameters": [ { "name": "walmart_feed", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The feed's uuid", "example": "019b2286-9fee-71de-9f64-154824d3aa4d" } } ], "responses": { "200": { "description": "The feed and its items", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/WalmartFeed" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "example": "ABC-123" }, "listing_id": { "type": [ "integer", "null" ], "description": "The channel's listing with this SKU, if there is one", "example": 1 }, "wpid": { "type": [ "string", "null" ], "description": "The Walmart product id Walmart assigned", "example": "1YKTCEME6DEH" }, "ingestion_status": { "type": "string", "description": "Walmart's result for this item, e.g. `SUCCESS` or `DATA_ERROR`", "example": "SUCCESS" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "description": { "type": "string" } }, "required": [ "type", "code", "description" ] } } }, "required": [ "sku", "listing_id", "wpid", "ingestion_status", "errors" ] } } }, "required": [ "items" ] } ] } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "019b2286-9fee-71de-9f64-154824d3aa4d", "feed_type": "MP_ITEM_MATCH", "status": "processed", "walmart_feed_id": "F129C19240844B97A3C6AD8F1A2C4997@AU8BAQA", "items_received": 1, "items_succeeded": 1, "items_failed": 0, "items_processing": 0, "errors": [], "submitted_at": "2026-09-28T15:00:05Z", "processed_at": "2026-09-28T15:04:40Z", "failed_at": null, "created_at": "2026-09-28T15:00:00Z", "items": [ { "sku": "ABC-123", "listing_id": 1, "wpid": "1YKTCEME6DEH", "ingestion_status": "SUCCESS", "errors": [] } ] } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } } } }, "/channels/walmart/catalog-items/{catalog_item_uuid}/prices": { "get": { "summary": "Show a Walmart catalog item's landed-price analytics", "description": "Summarises daily UTC landed-price observations of the Walmart buy box for one Walmart catalog item into calendar buckets over [start, end). Catalog prices are global per platform, so no listing, channel or merchant link is needed; the caller needs listings:view on the narrated account. A uuid that is not an existing Walmart catalog item returns 404. Days are UTC calendar days, weeks start on Monday and months on the first. Edge buckets are clipped to the range. Each observed currency is its own series; an item with no observations in the range returns an empty series array. Averages are per observation, not time-weighted, and the current UTC day may still gain observations.", "operationId": "show-walmart-catalog-item-prices", "tags": [ "Channels" ], "parameters": [ { "name": "catalog_item_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The Walmart catalog item's uuid", "example": "019b2286-9fee-80ea-9f64-154824d3aa4d" } }, { "name": "start", "in": "query", "required": true, "description": "First UTC day to include, as YYYY-MM-DD with a four-digit AD year from 0001 to 9999.", "schema": { "type": "string", "format": "date", "example": "2026-09-28" } }, { "name": "end", "in": "query", "required": true, "description": "UTC day after the last day to include, as YYYY-MM-DD with a four-digit AD year from 0001 to 9999. Must be after start, at most 731 days later.", "schema": { "type": "string", "format": "date", "example": "2026-10-03" } }, { "name": "granularity", "in": "query", "required": true, "description": "Bucket size: UTC calendar day, Monday-start week, or calendar month.", "schema": { "type": "string", "enum": [ "day", "week", "month" ], "example": "week" } } ], "responses": { "200": { "description": "Landed-price buckets per observed currency.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogItemPriceAnalytics" }, "examples": { "weekly": { "value": { "start": "2026-09-28", "end": "2026-10-03", "granularity": "week", "timezone": "UTC", "series": [ { "currency": "USD", "buckets": [ { "start": "2026-09-28", "end": "2026-10-03", "lowest_landed_price": "19.9900", "highest_landed_price": "21.0000", "average_landed_price": "20.3267", "observation_count": 3, "observed_days": 2 } ] } ] } }, "daily_with_gap": { "value": { "start": "2026-09-30", "end": "2026-10-02", "granularity": "day", "timezone": "UTC", "series": [ { "currency": "USD", "buckets": [ { "start": "2026-09-30", "end": "2026-10-01", "lowest_landed_price": "19.9900", "highest_landed_price": "19.9900", "average_landed_price": "19.9900", "observation_count": 1, "observed_days": 1 }, { "start": "2026-10-01", "end": "2026-10-02", "lowest_landed_price": null, "highest_landed_price": null, "average_landed_price": null, "observation_count": 0, "observed_days": 0 } ] } ] } }, "no_observations": { "value": { "start": "2026-09-01", "end": "2026-10-01", "granularity": "month", "timezone": "UTC", "series": [] } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/channels/walmart/listings/{listing}": { "post": { "summary": "Set up a listing on Walmart", "description": "Set up the listing's SKU as an offer on an item already in Walmart's catalogue (\"setup by match\", the `MP_ITEM_MATCH` feed). Walmart processes the feed asynchronously: the listing is marked submitted, and the returned feed reports the outcome through the Walmart feeds endpoints. When the feed finishes, the listing becomes synced (with its WPID) or unsynced.", "operationId": "push-walmart-listing", "tags": [ "Channels" ], "parameters": [ { "name": "listing", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of a listing on a Walmart channel", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "gtin": { "type": "string", "description": "The GTIN, UPC or EAN of the Walmart catalogue item to match (8, 12, 13 or 14 digits)", "example": "012345678905" }, "price": { "type": "number", "description": "The offer price, in the channel's marketplace currency", "exclusiveMinimum": 0, "example": 19.99 }, "shipping_weight_lb": { "type": [ "number", "null" ], "description": "The shipping weight in pounds. Defaults to the listing's weight; required when the listing has none.", "exclusiveMinimum": 0, "example": 1.5 }, "condition": { "type": [ "string", "null" ], "description": "The item condition. Defaults to `New`.", "enum": [ "New", "Pre-Owned: Like New", "Pre-Owned: Good", "Pre-Owned: Fair", "Restored", "Restored Premium", null ], "example": "New" } }, "required": [ "gtin", "price" ] } } } }, "responses": { "202": { "description": "The feed was requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WalmartFeed" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "019b2286-9fee-71de-9f64-154824d3aa4d", "feed_type": "MP_ITEM_MATCH", "status": "requested", "walmart_feed_id": null, "items_received": null, "items_succeeded": null, "items_failed": null, "items_processing": null, "errors": [], "submitted_at": null, "processed_at": null, "failed_at": null, "created_at": "2026-09-28T15:00:00Z" } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "description": "The request failed validation, the listing is not on a Walmart channel, or the channel is not connected", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "This Walmart channel is not connected." }, "errors": { "type": "object", "description": "A map of field names to arrays of error messages" } }, "required": [ "message" ] } } } } } }, "patch": { "summary": "Update listing attributes on Walmart", "description": "Requests partial product content and offer attribute updates for an existing United States Walmart listing through an MP_MAINTENANCE feed. Include only attributes to update, using Walmart attribute names inside orderable and visible. The listing SKU is supplied automatically; gtin defaults to the linked catalogue item. Walmart validates category-specific attributes asynchronously. The returned feed tracks submission and item-level errors. The local listing status and content are not changed by this request. WFS trade item and supply chain fields require WFS item setup instead. For dedicated SKU-based price and MSRP updates without a GTIN, use PATCH /channels/walmart/listings/{listing}/price, which submits PRICE_AND_PROMOTION.", "operationId": "update-walmart-listing", "tags": [ "Channels" ], "parameters": [ { "name": "listing", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of a listing on a Walmart channel", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "gtin": { "type": [ "string", "null" ], "pattern": "^(?:\\d{8}|\\d{12}|\\d{13}|\\d{14})$", "description": "GTIN, UPC or EAN (8, 12, 13 or 14 digits). Defaults to the linked Walmart catalogue GTIN. Required when the listing has no catalogue GTIN. For restored or GTIN-exempt items, use the identifier Walmart assigned to the existing item.", "example": "012345678905" }, "product_type": { "type": [ "string", "null" ], "maxLength": 255, "description": "The Walmart product type that keys visible. Defaults to the product type Walmart lists the item under; when supplied it must equal that product type. Ignored without visible.", "example": "T-Shirts" }, "visible": { "type": "object", "minProperties": 1, "additionalProperties": true, "description": "Product content attributes for the item's product type, using Walmart names (for example productName, shortDescription, mainImageUrl, productSecondaryImageURL, keyFeatures and category attributes). condition cannot be changed: it may only restate the live item's condition (`walmart.live_item.condition`), otherwise 422, and only for a product type whose spec has a condition attribute (many have none, such as Battle Ropes and Baby Blankets, and then any condition is refused as an attribute the product type does not have). Must meet Walmart's item spec for the product type: carry every attribute in `required` from GET /channels/walmart/listings/{listing}/content-requirements, plus any the spec requires for another attribute's value (for example warrantyText when has_written_warranty is \"Yes - Warranty Text\"), with each value meeting its spec rules (type, length, allowed values, item counts); no feed is sent otherwise.", "example": { "productName": "Updated product title", "keyFeatures": [ "Updated feature" ] } }, "orderable": { "type": "object", "minProperties": 1, "additionalProperties": true, "description": "Offer attributes using Walmart names (for example price, ShippingWeight, startDate, endDate and stateRestrictions). sku, productIdentifiers, specProductType, condition, skuUpdate and productIdUpdate are reserved and must be omitted. Use the dedicated /price endpoint for pricing-only updates.", "example": { "price": 19.99, "ShippingWeight": 1.5 } } }, "anyOf": [ { "required": [ "visible" ] }, { "required": [ "orderable" ] } ] } } } }, "responses": { "202": { "description": "The feed was requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WalmartFeed" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "019b2286-9fee-71de-9f64-154824d3aa4d", "feed_type": "MP_MAINTENANCE", "status": "requested", "walmart_feed_id": null, "items_received": null, "items_succeeded": null, "items_failed": null, "items_processing": null, "errors": [], "submitted_at": null, "processed_at": null, "failed_at": null, "created_at": "2026-09-28T15:00:00Z" } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "description": "Invalid attributes, missing GTIN, unsupported marketplace, a non-Walmart listing, a disconnected channel, or (with visible) no Walmart item for the listing's SKU, a SKU Walmart rejects, an item Walmart lists without a product type or a product_type that differs from the one Walmart lists the item under, a live product type Walmart has no spec for, or content that does not meet Walmart's item spec for that product type (a missing required or conditionally required attribute, a value breaking its rules, or an attribute the product type does not have); the message then names each violation and `errors` holds its messages under `visible.`, or under `visible` for one about the content as a whole (such as an attribute the product type does not have)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "This Walmart channel is not connected." }, "errors": { "type": "object", "description": "A map of field names to arrays of error messages" } }, "required": [ "message" ] } } } }, "502": { "description": "Walmart did not answer the live item lookup used to check the product type, or did not return its item spec for that product type", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Walmart did not return this item's product type. Try again later." } }, "required": [ "message" ] } } } } } } }, "/channels/walmart/listings/{listing}/price": { "patch": { "summary": "Update a Walmart listing price and MSRP", "description": "Queues a PRICE_AND_PROMOTION feed for an existing listing on a connected United States Walmart channel. Requires ListingsUpdate permission and the listing must belong to the current merchant and service provider context. The listing SKU is supplied automatically; no GTIN, catalogue link or product type is required. Supply a price and optionally msrp. Uses Walmart pricing specification 2.0.20240126-12_25_52-api with MPItem[].Promo&Discount. A 202 response means queued, not applied: monitor GET /channels/walmart/feeds/{walmart_feed} for submission and item-level ingestion errors. Filter channel feeds with feed_type=PRICE_AND_PROMOTION. The local listing status and content are unchanged. Promotion creation and deletion are not supported by this endpoint. Walmart reference: https://developer.walmart.com/us-marketplace/docs/update-bulk-prices.", "operationId": "update-walmart-listing-price", "tags": [ "Channels" ], "parameters": [ { "name": "listing", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of a listing on a Walmart channel", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "price": { "type": [ "number", "string" ], "description": "Selling price in USD, greater than zero, with at most two decimal places. Numeric strings are accepted and sent to Walmart as numbers.", "example": "19.99" }, "msrp": { "type": [ "number", "string" ], "description": "Optional MSRP in USD, non-negative, with at most two decimal places. Omit to leave it unchanged; null is not accepted. Numeric strings are accepted and sent to Walmart as numbers.", "example": "24.99" } }, "required": [ "price" ] }, "example": { "price": "19.99", "msrp": "24.99" } } } }, "responses": { "202": { "description": "The pricing feed was queued. Monitor its status and item-level ingestion errors using the feed endpoints.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WalmartFeed" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "019b2286-9fee-71de-9f64-154824d3aa4d", "feed_type": "PRICE_AND_PROMOTION", "status": "requested", "walmart_feed_id": null, "items_received": null, "items_succeeded": null, "items_failed": null, "items_processing": null, "errors": [], "submitted_at": null, "processed_at": null, "failed_at": null, "created_at": "2026-09-28T15:00:00Z" } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/channels/walmart/listings/{listing}/content-requirements": { "get": { "summary": "Show the content requirements of a Walmart listing", "description": "The content (`Visible`) attributes Walmart's item spec defines for the product type Walmart lists the item under, for building a content form. `required` is every attribute a content change must carry: the spec's unconditional `required` list (`spec_required`) united with Walmart's content standards (`content_standards`: `productName`, `shortDescription`, `mainImageUrl`, `keyFeatures`, kept only where the product type has them). The live `MP_MAINTENANCE` spec marks none of the content standards required (for many product types it has no unconditional `required` list at all), yet Walmart's ingestion refuses a content change without them (`EXT_DATA_ERROR_05045574625354`; https://public.walmart.com/content/ContentStandards/en_us/importance-of-content-standards.html), so they come from that ingestion evidence rather than the spec. `conditional` lists the spec's `allOf` `if`/`then` rules as the attribute that triggers them (`when`) and the attributes they then require (`then`); it is listed as Walmart gives it and not evaluated here, and the value that triggers a rule (e.g. which `has_written_warranty` answer calls for `warrantyText` rather than `warrantyURL`) is not included. A content change on `PATCH /channels/walmart/listings/{listing}` that misses a `required` attribute, misses one a `conditional` rule requires for the value sent, or has a value breaking its spec rules is refused with 422 before any feed is sent. Walmart may still refuse a content change on rules this check leaves to Walmart (such as value formats, or rules outside the spec); those come back as the feed's ingestion errors. Read from Walmart's `POST /v3/items/spec` (https://developer.walmart.com/us-marketplace/reference/getspec) for the `MP_MAINTENANCE` feed type at the version our maintenance feed is sent with, and cached for 24 hours per marketplace, feed type and product type.", "operationId": "show-walmart-content-requirements", "tags": [ "Channels" ], "parameters": [ { "name": "listing", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of a listing on a Walmart channel", "example": 1 } } ], "responses": { "200": { "description": "The content requirements", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "product_type": { "type": "string", "description": "The product type Walmart lists the item under", "example": "Battle Ropes" }, "required": { "type": "array", "description": "Walmart attribute names every content change must carry: `spec_required` and `content_standards` together", "items": { "type": "string" }, "example": [ "productName", "shortDescription", "mainImageUrl", "keyFeatures" ] }, "spec_required": { "type": "array", "items": { "type": "string" }, "description": "Walmart attribute names the spec requires unconditionally; often empty", "example": [] }, "content_standards": { "type": "array", "items": { "type": "string" }, "description": "Walmart's content standards (`productName`, `shortDescription`, `mainImageUrl`, `keyFeatures`) the product type has; Walmart's ingestion refuses a content change without them although the spec does not mark them required", "example": [ "productName", "shortDescription", "mainImageUrl", "keyFeatures" ] }, "conditional": { "type": "array", "description": "The spec's `allOf` `if`/`then` rules, not evaluated: once `when` is given, Walmart may require the `then` attributes, depending on its value", "items": { "type": "object", "properties": { "when": { "type": "string", "description": "The attribute that triggers the rule", "example": "has_written_warranty" }, "then": { "type": "array", "items": { "type": "string" }, "description": "The attributes the rule may then require", "example": [ "warrantyText", "warrantyURL" ] } }, "additionalProperties": false, "required": [ "when", "then" ] } }, "optional": { "type": "array", "description": "The other Walmart attribute names the product type accepts", "items": { "type": "string" }, "example": [ "brand", "productSecondaryImageURL" ] } }, "additionalProperties": false, "required": [ "product_type", "required", "spec_required", "content_standards", "conditional", "optional" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "description": "The listing does not exist for this account, or Walmart has no item with a product type for its SKU", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Walmart has no item with a product type for this SKU." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" }, "502": { "description": "Walmart did not return the live item or its item spec", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Walmart did not return this item's content requirements. Try again later." } }, "required": [ "message" ] } } } } } } }, "/channels/walmart/listings/{listing}/content": { "get": { "summary": "Get current Walmart listing content", "description": "Fetches fresh content directly from Walmart for a listing on a connected Walmart channel. Resolves the exact seller SKU with GET /v3/items/{sku}, then searches GET /v3/items/walmart/search using the live item ID, or its normalized GTIN/UPC when Walmart omits the item ID. Returns only an unambiguous matching catalog item, with a matching condition when both responses include one. No local catalog link is required. Requires ListingsView permission and the listing must belong to the current merchant and service provider context. This is a partial read of Walmart's published catalog, not a complete maintenance feed or saved draft. Unpublished items may not appear in catalog search. Missing text fields are null and missing images are an empty array; never use those missing values to overwrite a draft. Key features and category-specific attributes are not exposed by this endpoint, so use GET /channels/walmart/listings/{listing}/content-requirements to determine what else an update needs. For PATCH /channels/walmart/listings/{listing}, map title to visible.productName, description to visible.shortDescription and brand to visible.brand; image URLs can prefill visible.mainImageUrl and visible.productSecondaryImageURL after review. The response is not guaranteed to satisfy Walmart's maintenance requirements. Text and HTML are preserved as Walmart returns them. Walmart API reference: https://developer.walmart.com/us-marketplace/reference/getsearchresult.", "operationId": "show-walmart-listing-content", "tags": [ "Channels" ], "parameters": [ { "name": "listing", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of a listing on a Walmart channel" } } ], "responses": { "200": { "description": "Current available Walmart catalog content", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "listing_id", "sku", "item_id", "gtin", "product_type", "title", "description", "brand", "images" ], "properties": { "listing_id": { "type": "integer" }, "sku": { "type": "string" }, "item_id": { "type": "string", "description": "The matching Walmart catalog item ID" }, "gtin": { "type": [ "string", "null" ], "description": "Normalized 14-digit GTIN from the live seller item, or the catalog result" }, "product_type": { "type": [ "string", "null" ], "description": "Product type from the live seller item" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ], "description": "Walmart catalog description; may contain HTML" }, "brand": { "type": [ "string", "null" ] }, "images": { "type": "array", "items": { "type": "string" }, "description": "Available non-empty image URLs in Walmart response order" } } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "description": "Listing outside the current context, missing seller item, rejected identifier, missing catalog identifier, or no unambiguous matching published catalog item" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" }, "502": { "description": "Walmart authentication, item lookup or catalog search failed or returned a malformed response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Walmart did not return this item's content. Try again later." } } } } } } } } }, "/channels/walmart/listings/{listing}/wfs-conversion-requirements": { "get": { "summary": "Show WFS conversion requirements", "operationId": "show-walmart-wfs-conversion-requirements", "tags": [ "Channels" ], "description": "Resolves the listing live by SKU on its connected US Walmart channel and returns the OMNI_WFS conversion JSON schemas at 5.0.20260803-17_50_56-api, also used by conversion validation and feed generation. No local catalog link is needed. Each schema retains Walmart properties, required, additionalProperties, types, bounds, enums and full if/then/else conditions; clients must evaluate value conditions rather than treating every then field as unconditionally required. visible_schema applies inside Visible[product_type], orderable_schema to Orderable and trade_item_schema to TradeItem. feed_schema is the complete envelope restricted to the live product type. See the conversion endpoint for snake_case input mappings. These are conversion requirements, distinct from content-requirements (MP_MAINTENANCE). Requirements are cached for 24 hours by marketplace, OMNI_WFS, exact version and product type.", "parameters": [ { "name": "listing", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of a listing on a Walmart channel", "example": 1 } } ], "responses": { "200": { "description": "The WFS conversion requirements for the live product type", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "visible_schema", "orderable_schema", "trade_item_schema", "feed_schema", "product_type", "feed_type", "spec_version" ], "properties": { "visible_schema": { "type": "object", "additionalProperties": true, "description": "Product-type Visible JSON schema" }, "orderable_schema": { "type": "object", "additionalProperties": true, "description": "Orderable JSON schema including hazard and battery conditions" }, "trade_item_schema": { "type": "object", "additionalProperties": true, "description": "TradeItem JSON schema including package dimensions" }, "feed_schema": { "type": "object", "additionalProperties": true, "description": "Complete generated feed JSON schema" }, "product_type": { "type": "string", "example": "Battle Ropes" }, "feed_type": { "type": "string", "enum": [ "OMNI_WFS" ] }, "spec_version": { "type": "string", "enum": [ "5.0.20260803-17_50_56-api" ] } } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "description": "Listing not visible to the selected merchant, or Walmart has no live item with a product type for this SKU" }, "422": { "description": "Listing is not on a connected US Walmart channel, or Walmart has no conversion schema for the live product type. errors contains messages keyed by listing or product_type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Every available validation error, grouped by attribute path. Each path contains all messages for that attribute." } }, "required": [ "message", "errors" ] } } } }, "502": { "description": "Walmart did not answer the live item lookup used to check the product type, or did not return its item spec for that product type", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Walmart did not return this item's product type. Try again later." } }, "required": [ "message" ] } } } } } } }, "/channels/walmart/listings/{listing}/convert-to-wfs": { "post": { "summary": "Convert a Walmart listing to WFS", "description": "Requests conversion of an existing United States Walmart Marketplace listing through an OMNI_WFS feed at specification 5.0.20260803-17_50_56-api. The live SKU lookup supplies the product type and GTIN/UPC; a local catalog link is not required. GET /channels/walmart/listings/{listing}/wfs-conversion-requirements returns the exact conversion schemas, including field placement, types, enums and value-dependent requirements. The content-requirements endpoint describes MP_MAINTENANCE and is not a conversion schema. The generated feed is validated before submission. A 202 means queued for asynchronous processing, not converted; monitor the returned feed for ingestion errors.", "operationId": "convert-walmart-listing-to-wfs", "tags": [ "Channels" ], "parameters": [ { "name": "listing", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of a listing on a Walmart channel", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_type": { "type": [ "string", "null" ], "maxLength": 255, "description": "The Walmart product type used as the key in the feed's Visible block. Defaults to the product type Walmart lists the item under; when supplied it must equal that product type.", "example": "Battle Ropes" }, "price": { "type": "number", "description": "The item price in the Walmart channel's marketplace currency", "exclusiveMinimum": 0, "example": 19.99 }, "country_of_origin_assembly": { "type": "array", "minItems": 1, "maxItems": 10, "uniqueItems": true, "items": { "type": "string", "minLength": 2, "maxLength": 2, "example": "US" } }, "battery_technology_type": { "type": "string", "enum": [ "Mercury", "Carbon Zinc", "Lead Acid (Non-Spillable)", "Alkaline", "Does Not Contain a Battery", "Lithium Primary (Lithium Metal)", "Nickel Cadmium", "Lithium Ion", "Nickel Metal Hydride", "Lead Acid", "Silver", "Magnesium" ], "example": "Does Not Contain a Battery" }, "electronics_indicator": { "type": "boolean", "example": false }, "chemical_aerosol_pesticide": { "type": "boolean", "const": false, "deprecated": true, "description": "Legacy compatibility: false supplies No for any omitted is_chemical/is_aerosol/is_pesticide flags. True is rejected because it cannot identify which hazard applies; supply the three explicit flags." }, "state_restrictions_text": { "type": [ "string", "null" ], "description": "Walmart's state restriction value. Defaults to `None`.", "example": "None" }, "each": { "$ref": "#/components/schemas/WfsPackageDimensions", "description": "Packaged sellable unit, mapped to TradeItem.each.eachWidth/eachHeight/eachDepth/eachWeight. Inches and pounds, at most four decimal places. GTINs are placed only in Orderable.productIdentifiers." }, "visible": { "type": "object", "description": "Attributes placed exactly in SupplierItem[0].Visible[live product type]. Must meet visible_schema from the WFS requirements endpoint. No maintenance content standards are added. Unknown fields are rejected, never stripped. For Battle Ropes this release requires productName, brand, isProp65WarningRequired, mainImageUrl, netContent and condition (New). isProp65WarningRequired=Yes requires prop65WarningText.", "minProperties": 1, "additionalProperties": true, "example": { "productName": "Tapout 40ft Battle Rope", "brand": "Tapout", "mainImageUrl": "https://example.com/rope.jpg", "condition": "New", "isProp65WarningRequired": "No", "netContent": { "productNetContentMeasure": 1, "productNetContentUnit": "Each" } } }, "end_date": { "type": "string", "format": "date", "example": "2027-01-01", "description": "Future UTC date, mapped to Orderable.endDate at midnight." }, "inner_pack": { "type": "null", "deprecated": true, "description": "Only null or omission is accepted. This conversion version does not support TradeItem.innerPack." }, "is_chemical": { "type": "boolean", "description": "Maps to Orderable.isChemical as Yes/No. Yes triggers the conditional compliance requirements in orderable_schema.", "example": false }, "is_aerosol": { "type": "boolean", "description": "Maps to Orderable.isAerosol as Yes/No. Yes triggers the conditional compliance requirements in orderable_schema.", "example": false }, "is_pesticide": { "type": "boolean", "description": "Maps to Orderable.isPesticide as Yes/No. Yes triggers the conditional compliance requirements in orderable_schema.", "example": false }, "orderable": { "type": "object", "additionalProperties": true, "description": "Additional attributes placed in SupplierItem[0].Orderable, preserving Walmart field names and JSON types. Must meet orderable_schema, including conditional requirements for hazards and batteries: labelImage, safetyDataSheet, numberOfHazardousComponents, hasBatteries, batterySize, lithiumIonBatteries, lithiumMetalBatteries, required_storage_condition and pesticide_type when applicable. sku, productIdentifiers, price, stateRestrictions, electronicsIndicator, batteryTechnologyType, isChemical, isAerosol, isPesticide and endDate are managed by the listing or top-level request fields and cannot be supplied here. Unsupported attributes are rejected." } }, "required": [ "price", "country_of_origin_assembly", "battery_technology_type", "electronics_indicator", "each", "visible", "end_date" ], "anyOf": [ { "required": [ "is_chemical", "is_aerosol", "is_pesticide" ] }, { "required": [ "chemical_aerosol_pesticide" ], "properties": { "chemical_aerosol_pesticide": { "const": false } } } ] } } } }, "responses": { "202": { "description": "The WFS conversion feed was requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WalmartFeed" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "description": "All available request and conversion-schema validation errors are returned together in errors. Content errors use visible., extra compliance errors use orderable., and whole-object errors use visible or orderable. Final feed errors identify the generated Walmart path. No feed is queued. Errors also cover unavailable GTIN/UPC, unknown/mismatched live product type, disconnected or non-US channels, ambiguous legacy hazard=true and unsupported inner packs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Every available validation error, grouped by attribute path. Each path contains all messages for that attribute." } }, "required": [ "message", "errors" ] } } } }, "502": { "description": "Walmart did not answer the live item lookup used to check the product type, or did not return its item spec for that product type", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Walmart did not return this item's product type. Try again later." } }, "required": [ "message" ] } } } } } }, "WfsInnerPack": { "allOf": [ { "$ref": "#/components/schemas/WfsPackageDimensions" }, { "type": "object", "properties": { "qty_sellable_items": { "type": "integer", "minimum": 1 } }, "required": [ "qty_sellable_items" ] } ] } }, "/channels/walmart/{channel}/wfs/inbound-orders": { "get": { "summary": "Index a Walmart channel's WFS inbound orders", "description": "The channel's Walmart Fulfillment Services inbound orders, newest first.", "operationId": "index-wfs-inbound-orders", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the Walmart channel", "example": 1 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "submitted", "rejected", "closed", "cancelled" ] }, "description": "Only orders with this status" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "Only orders whose `inbound_order_id` contains this text, case-insensitively" }, { "name": "page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Page" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "The number of items per page. Defaults to 10.", "minimum": 1, "maximum": 100, "example": 10 } } ], "responses": { "200": { "description": "A paginated list of inbound orders", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WfsInboundOrder" } } }, "required": [ "data" ] } ] }, "examples": { "example": { "value": { "data": [ { "uuid": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90", "inbound_order_id": "PO-2026-0042", "channel_id": 1024, "merchant_id": 1042, "status": "submitted", "item_count": 1, "unit_count": 120, "shipment_ids": [ "SHP-8812" ], "errors": [], "consecutive_failure_count": 0, "submitted_at": "2026-09-29T14:02:11Z", "rejected_at": null, "cancellation_requested_at": null, "last_reconciled_at": "2026-09-29T15:00:03Z", "created_at": "2026-09-29T13:58:40Z", "updated_at": "2026-09-29T15:00:03Z" }, { "uuid": "019b2c3e-12aa-80ee-8c07-5f1e2d3c4b5a", "inbound_order_id": "PO-2026-0041", "channel_id": 1024, "merchant_id": 1042, "status": "rejected", "item_count": 2, "unit_count": 48, "shipment_ids": [], "errors": [ { "code": "ERR_EXT_DATA_0801001", "field": "items[1].itemQty", "description": "Item quantity is invalid." } ], "consecutive_failure_count": 0, "submitted_at": null, "rejected_at": "2026-09-29T12:40:10Z", "cancellation_requested_at": null, "last_reconciled_at": null, "created_at": "2026-09-29T12:31:02Z", "updated_at": "2026-09-29T12:40:10Z" } ], "total": 2, "current_page": 1, "last_page": 1, "per_page": 10, "from": 1, "to": 2 } } } } } }, "400": { "description": "The channel is not a Walmart channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Channel type is not Walmart" } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } }, "post": { "summary": "Draft a WFS inbound order", "description": "Create a draft inbound order on a Walmart channel with its return address and items. Nothing is sent to Walmart until the order is submitted.", "operationId": "draft-wfs-inbound-order", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the Walmart channel", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "inbound_order_id": { "type": "string", "description": "Your id for the order. Must be unique on the channel.", "minLength": 1, "maxLength": 100, "example": "PO-2026-0042" }, "return_address": { "type": "object", "description": "Where Walmart returns inventory it cannot receive", "properties": { "address_line_1": { "type": "string", "maxLength": 255, "example": "100 Main St" }, "address_line_2": { "type": [ "string", "null" ], "maxLength": 255, "example": null }, "city": { "type": "string", "maxLength": 255, "example": "Bentonville" }, "state_code": { "type": "string", "maxLength": 10, "example": "AR" }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2 country code, exactly 2 characters", "example": "US" }, "postal_code": { "type": "string", "maxLength": 20, "example": "72712" } }, "required": [ "address_line_1", "city", "state_code", "country_code", "postal_code" ] }, "inventory_transfer_service": { "type": "boolean", "description": "Use Walmart's Inventory Transfer Service, sent as `inboundServices.inventoryTransferService: Y`. Omitted or false is self-distribution, Walmart's default, and nothing is sent.", "example": false }, "items": { "type": "array", "description": "The SKUs to send, each at most once", "minItems": 1, "maxItems": 500, "items": { "type": "object", "properties": { "sku": { "type": "string", "description": "Must be unique within the order (compared case-sensitively)", "maxLength": 255, "example": "SKU-1" }, "gtin": { "type": "string", "description": "The item's GTIN, UPC or EAN: 8, 12, 13 or 14 digits; the check digit is not validated", "pattern": "^(\\d{8}|\\d{12,14})$", "example": "00012345678905" }, "item_description": { "type": "string", "maxLength": 255, "example": "Widget" }, "item_qty": { "type": "integer", "description": "The total units of the SKU. With case packs it must equal `vendor_pack_qty` times `inner_pack_qty`.", "minimum": 1, "example": 120 }, "vendor_pack_qty": { "type": [ "integer", "null" ], "description": "The number of cases. Send together with `inner_pack_qty` for case-packed items; omit both for loose units.", "minimum": 1, "example": 12 }, "inner_pack_qty": { "type": [ "integer", "null" ], "description": "The units per case. Send together with `vendor_pack_qty`.", "minimum": 1, "example": 10 }, "expected_delivery_date": { "type": "string", "description": "When the item is expected at Walmart, as `YYYY-MM-DD`", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-10-15" }, "item_labeling": { "type": "boolean", "description": "Ask WFS to label the units (the Item Labeling prep service). Defaults to false.", "example": false } }, "required": [ "sku", "gtin", "item_description", "item_qty", "expected_delivery_date" ] } } }, "required": [ "inbound_order_id", "return_address", "items" ] } } } }, "responses": { "201": { "description": "The draft order", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WfsInboundOrderDetail" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90", "inbound_order_id": "PO-2026-0042", "channel_id": 1024, "merchant_id": 1042, "status": "draft", "item_count": 1, "unit_count": 120, "shipment_ids": [], "errors": [], "consecutive_failure_count": 0, "submitted_at": null, "rejected_at": null, "cancellation_requested_at": null, "last_reconciled_at": null, "created_at": "2026-09-29T13:58:40Z", "updated_at": "2026-09-29T13:58:40Z", "return_address": { "address_line_1": "100 Main St", "address_line_2": null, "city": "Bentonville", "state_code": "AR", "country_code": "US", "postal_code": "72712" }, "inventory_transfer_service": false, "items": [ { "sku": "SKU-1", "gtin": "00012345678905", "item_description": "Widget", "item_qty": 120, "vendor_pack_qty": 12, "inner_pack_qty": 10, "expected_delivery_date": "2026-10-15", "item_labeling": false } ], "shipments": [], "timeline": [ { "event_uuid": "019b2c41-7b1d-8010-a3f2-6c1d0e9b8a70", "event_type": "item_added", "user_uuid": "019a0f11-2c3d-8001-9e4f-5a6b7c8d9e0f", "shipment_id": null, "details": null, "occurred_at": "2026-09-29T13:58:40Z" }, { "event_uuid": "019b2c41-7b1c-8010-9f11-2b3c4d5e6f70", "event_type": "drafted", "user_uuid": "019a0f11-2c3d-8001-9e4f-5a6b7c8d9e0f", "shipment_id": null, "details": null, "occurred_at": "2026-09-29T13:58:40Z" } ] } } } } } } }, "400": { "description": "The channel is not a Walmart channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Channel type is not Walmart" } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "description": "The request failed validation, or an inbound order with this `inbound_order_id` already exists on the channel (in which case there is no `errors`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An inbound order 'PO-2026-0042' already exists on this channel." }, "errors": { "type": "object", "description": "A map of field names to arrays of error messages" } }, "required": [ "message" ] } } } } } } }, "/channels/walmart/{channel}/wfs/holds": { "get": { "summary": "Search a GTIN's WFS hazmat compliance holds", "description": "Asks Walmart whether an item is on a WFS hazmat compliance hold. `in_review` clears within about 72 business hours; `action_needed` means the item data must be fixed and converted to WFS again; `prohibited` means the item cannot be sold through WFS. An item with several errors is one row per error. Nothing is stored. Walmart: https://developer.walmart.com/us-marketplace/reference/wercsfeedback", "operationId": "index-wfs-item-holds", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the Walmart channel", "example": 1 } }, { "name": "gtin", "in": "query", "required": true, "schema": { "type": "string", "description": "The item's GTIN, UPC or EAN: 8, 12, 13 or 14 digits", "pattern": "^(\\d{8}|\\d{12,14})$", "example": "00704551260905" } } ], "responses": { "200": { "description": "The holds, newest first; empty when the item is not on hold", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "gtin": { "type": "string", "example": "00051494401255" }, "sku": { "type": [ "string", "null" ], "example": "SD-AB-12345" }, "status": { "type": "string", "enum": [ "in_review", "action_needed", "prohibited" ], "example": "action_needed" }, "field": { "type": [ "string", "null" ], "description": "The item attribute Walmart flagged, or null when Walmart gave no error", "example": "batteryTechnologyType" }, "description": { "type": [ "string", "null" ], "description": "What to fix, or null when Walmart gave no error", "example": "This item may contain a lithium or lead acid battery that requires additional compliance information, check the 'Battery Type' field." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2021-08-26T15:48:44Z" } }, "required": [ "gtin", "sku", "status", "field", "description", "updated_at" ] } } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": [ { "gtin": "00051494401255", "sku": "SD-AB-12345", "status": "action_needed", "field": "batteryTechnologyType", "description": "This item may contain a lithium or lead acid battery that requires additional compliance information, check the 'Battery Type' field.", "updated_at": "2021-08-26T15:48:44Z" } ] } }, "empty": { "value": { "data": [] } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "description": "Not Found — the channel does not exist" }, "422": { "description": "The GTIN is invalid, or Walmart refused the search (`errors.walmart` carries its codes)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "A GTIN is 8, 12, 13 or 14 digits." }, "errors": { "type": "object", "description": "A map of field names to arrays of error messages; `walmart` lists Walmart's refusal as `code: description`." } }, "required": [ "message", "errors" ] } } } }, "502": { "description": "Walmart could not answer; `errors` carries its codes", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Walmart could not return the hazmat holds." }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "500" }, "message": { "type": "string", "example": "Gateway Timeout" }, "details": { "type": "string", "example": "Illuminate\\Http\\Client\\RequestException" } }, "required": [ "code", "message", "details" ] } } }, "required": [ "message", "errors" ] } } } } } } }, "/channels/walmart/wfs/inbound-orders/{wfs_inbound_order}": { "get": { "summary": "Show a WFS inbound order", "description": "One inbound order with its items, its shipments (with their items and carrier bookings) and its timeline.", "operationId": "show-wfs-inbound-order", "tags": [ "Channels" ], "parameters": [ { "name": "wfs_inbound_order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The inbound order's uuid", "example": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90" } } ], "responses": { "200": { "description": "The inbound order", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WfsInboundOrderDetail" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90", "inbound_order_id": "PO-2026-0042", "channel_id": 1024, "merchant_id": 1042, "status": "submitted", "item_count": 1, "unit_count": 120, "shipment_ids": [ "SHP-8812" ], "errors": [], "consecutive_failure_count": 0, "submitted_at": "2026-09-29T14:02:11Z", "rejected_at": null, "cancellation_requested_at": null, "last_reconciled_at": "2026-09-29T15:00:03Z", "created_at": "2026-09-29T13:58:40Z", "updated_at": "2026-09-29T15:00:03Z", "return_address": { "address_line_1": "100 Main St", "address_line_2": null, "city": "Bentonville", "state_code": "AR", "country_code": "US", "postal_code": "72712" }, "inventory_transfer_service": false, "items": [ { "sku": "SKU-1", "gtin": "00012345678905", "item_description": "Widget", "item_qty": 120, "vendor_pack_qty": 12, "inner_pack_qty": 10, "expected_delivery_date": "2026-10-15", "item_labeling": false } ], "shipments": [ { "shipment_id": "SHP-8812", "fc_name": "DFW5", "ship_to_address": { "address_line_1": "1 Walmart Way", "address_line_2": null, "city": "Dallas", "state_code": "TX", "country_code": "US", "postal_code": "75201" }, "status": "pending_shipment_details", "expected_delivery_date": "2026-10-15", "updated_expected_delivery_date": null, "actual_delivery_date": null, "requested_units": 120, "received_units": 0, "damaged_units": 0, "carrier_name": null, "tracking_numbers": [], "allocated_at": "2026-09-29T14:02:11Z", "items": [ { "sku": "SKU-1", "gtin": "00012345678905", "requested_qty": 120, "received_qty": 0, "damaged_qty": 0 } ], "carrier_booking": { "quote_type": "LTL", "quote_id": "Q-1", "carrier_id": "C-9", "carrier_name": "Acme Freight", "currency": "USD", "net_charge_cents": 18950, "state": "live", "terms_accepted_at": "2026-09-29T14:30:00Z", "booked_at": "2026-09-29T14:30:02Z", "cancel_by": "2026-09-29T15:30:02Z", "cancelled_at": null, "invalidated_at": null, "ship_date": "2026-10-01T00:00:00Z", "label_generated_at": null, "pickup": { "confirmation_number": "PU-77", "date": "2026-10-01", "ready_time": "09:00", "close_time": "17:00", "status": "SCHEDULED" } } } ], "timeline": [ { "event_uuid": "019b2c4a-1f01-8010-a3f2-6c1d0e9b8a70", "event_type": "pickup_observed", "user_uuid": null, "shipment_id": "SHP-8812", "details": null, "occurred_at": "2026-09-29T14:31:00Z" }, { "event_uuid": "019b2c4a-1e01-8010-a3f2-6c1d0e9b8a70", "event_type": "carrier_booked", "user_uuid": "019a0f11-2c3d-8001-9e4f-5a6b7c8d9e0f", "shipment_id": "SHP-8812", "details": null, "occurred_at": "2026-09-29T14:30:02Z" }, { "event_uuid": "019b2c4a-1d01-8010-a3f2-6c1d0e9b8a70", "event_type": "submitted", "user_uuid": null, "shipment_id": null, "details": null, "occurred_at": "2026-09-29T14:02:11Z" }, { "event_uuid": "019b2c4a-1c01-8010-a3f2-6c1d0e9b8a70", "event_type": "item_added", "user_uuid": "019a0f11-2c3d-8001-9e4f-5a6b7c8d9e0f", "shipment_id": null, "details": null, "occurred_at": "2026-09-29T13:58:40Z" }, { "event_uuid": "019b2c4a-1b01-8010-a3f2-6c1d0e9b8a70", "event_type": "drafted", "user_uuid": "019a0f11-2c3d-8001-9e4f-5a6b7c8d9e0f", "shipment_id": null, "details": null, "occurred_at": "2026-09-29T13:58:40Z" } ] } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } } } }, "/channels/walmart/wfs/inbound-orders/{wfs_inbound_order}/items": { "put": { "summary": "Replace the items of a WFS inbound order", "description": "Replace the item set of a draft or rejected inbound order before it is submitted again. A rejected order keeps its `inbound_order_id`: Walmart expects the corrected order to be resubmitted under the same id. Nothing is sent to Walmart until the order is submitted.", "operationId": "update-wfs-inbound-order-items", "tags": [ "Channels" ], "parameters": [ { "name": "wfs_inbound_order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The inbound order's uuid", "example": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The order's complete item set, each SKU at most once. SKUs on the order but not in the list are removed, new SKUs are added, and a SKU whose fields changed is replaced; an unchanged SKU records nothing.", "minItems": 1, "maxItems": 500, "items": { "type": "object", "properties": { "sku": { "type": "string", "description": "Must be unique within the order (compared case-sensitively)", "maxLength": 255, "example": "SKU-1" }, "gtin": { "type": "string", "description": "The item's GTIN, UPC or EAN: 8, 12, 13 or 14 digits; the check digit is not validated", "pattern": "^(\\d{8}|\\d{12,14})$", "example": "00012345678905" }, "item_description": { "type": "string", "maxLength": 255, "example": "Widget" }, "item_qty": { "type": "integer", "description": "The total units of the SKU. With case packs it must equal `vendor_pack_qty` times `inner_pack_qty`.", "minimum": 1, "example": 120 }, "vendor_pack_qty": { "type": [ "integer", "null" ], "description": "The number of cases. Send together with `inner_pack_qty` for case-packed items; omit both for loose units.", "minimum": 1, "example": 12 }, "inner_pack_qty": { "type": [ "integer", "null" ], "description": "The units per case. Send together with `vendor_pack_qty`.", "minimum": 1, "example": 10 }, "expected_delivery_date": { "type": "string", "description": "When the item is expected at Walmart, as `YYYY-MM-DD`", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-10-15" }, "item_labeling": { "type": "boolean", "description": "Ask WFS to label the units (the Item Labeling prep service). Omit to keep the saved choice of an item already on the order; a new item defaults to false.", "example": false } }, "required": [ "sku", "gtin", "item_description", "item_qty", "expected_delivery_date" ] } }, "inventory_transfer_service": { "type": "boolean", "description": "Use Walmart's Inventory Transfer Service, sent as `inboundServices.inventoryTransferService: Y`. Omitted or false is self-distribution, Walmart's default, and nothing is sent. Omitted leaves the order's choice unchanged.", "example": false } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "The inbound order with its new items", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WfsInboundOrderDetail" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90", "inbound_order_id": "PO-2026-0042", "channel_id": 1024, "merchant_id": 1042, "status": "rejected", "item_count": 1, "unit_count": 120, "shipment_ids": [], "errors": [ { "code": "ERR_EXT_DATA_0801001", "field": "items[0].itemQty", "description": "Item quantity is invalid." } ], "consecutive_failure_count": 0, "submitted_at": null, "rejected_at": "2026-09-29T14:02:11Z", "cancellation_requested_at": null, "last_reconciled_at": null, "created_at": "2026-09-29T13:58:40Z", "updated_at": "2026-09-29T14:30:00Z", "return_address": { "address_line_1": "100 Main St", "address_line_2": null, "city": "Bentonville", "state_code": "AR", "country_code": "US", "postal_code": "72712" }, "inventory_transfer_service": false, "items": [ { "sku": "SKU-1", "gtin": "00012345678905", "item_description": "Widget", "item_qty": 120, "vendor_pack_qty": 12, "inner_pack_qty": 10, "expected_delivery_date": "2026-10-15", "item_labeling": false } ], "shipments": [], "timeline": [ { "event_uuid": "019b2c4a-3a01-8010-a3f2-6c1d0e9b8a70", "event_type": "item_added", "user_uuid": "019a0f11-2c3d-8001-9e4f-5a6b7c8d9e0f", "shipment_id": null, "details": null, "occurred_at": "2026-09-29T14:30:00Z" }, { "event_uuid": "019b2c4a-2a01-8010-a3f2-6c1d0e9b8a70", "event_type": "item_removed", "user_uuid": "019a0f11-2c3d-8001-9e4f-5a6b7c8d9e0f", "shipment_id": null, "details": null, "occurred_at": "2026-09-29T14:30:00Z" }, { "event_uuid": "019b2c4a-1d01-8010-a3f2-6c1d0e9b8a70", "event_type": "rejected", "user_uuid": null, "shipment_id": null, "details": null, "occurred_at": "2026-09-29T14:02:11Z" } ] } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "409": { "$ref": "#/components/schemas/WfsInboundOrderBusy" }, "422": { "description": "The request failed validation, or the order is neither draft nor rejected, even when the body would change nothing (in which case there is no `errors`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Cannot edit the items of an inbound order unless it is Draft or Rejected." }, "errors": { "type": "object", "description": "A map of field names to arrays of error messages. Absent when the order's state refused the request." } }, "required": [ "message" ] } } } } } } }, "/channels/walmart/wfs/inbound-orders/{wfs_inbound_order}/preview": { "post": { "summary": "Preview the destinations and ITS fees of a WFS inbound order", "description": "Asks Walmart where the order's units would go, both with Inventory Transfer Service (ITS) and with self-distribution, and what ITS would cost. Walmart's figures are estimates: routing and fees are fixed when the order is submitted. Only Draft and Rejected orders can be previewed. Nothing is stored except a `preview_fetched` timeline entry. Walmart: https://developer.walmart.com/us-marketplace/reference/inboundpreview", "operationId": "preview-wfs-inbound-order", "tags": [ "Channels" ], "parameters": [ { "name": "wfs_inbound_order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The inbound order's uuid", "example": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "item_labeling_skus": { "type": "array", "description": "The SKUs to preview with the Item Labeling prep service, replacing the items' own choice for this preview only. Omit to use the items' own choice.", "maxItems": 500, "items": { "type": "string", "maxLength": 255, "example": "SKU-1" } } } } } } }, "responses": { "200": { "description": "Walmart's preview", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "destinations": { "type": "array", "description": "Every destination Walmart proposed, for each way of shipping", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "inventory_transfer_service", "self_distribution", "wfs", "unknown" ], "description": "`inventory_transfer_service` when the units go to a transfer station under ITS (Walmart's `inbound`), `self_distribution` when they go straight to fulfilment centres (Walmart's `selfMirroring`), `wfs` for Walmart's `wfs` single-destination/self-distribution preview (the only type seen live so far), `unknown` for a preview type Walmart added that is not mapped yet (see `walmart_type`)", "example": "wfs" }, "walmart_type": { "type": "string", "description": "Walmart's own `previewType` for this destination, verbatim", "example": "inbound" }, "ship_node": { "type": [ "string", "null" ], "example": "4093" }, "node_type": { "type": [ "string", "null" ], "description": "Walmart's node type, e.g. `FC` or `ICC`", "example": "ICC" }, "is_sortable": { "type": [ "boolean", "null" ], "example": true }, "is_non_sortable": { "type": [ "boolean", "null" ], "example": false }, "ship_to_address": { "type": [ "object", "null" ], "description": "Where to send the units, or null when Walmart gave no address", "properties": { "fc_name": { "type": [ "string", "null" ], "example": "LAX2T" }, "address_line_1": { "type": "string", "example": "6720 Kimball Ave" }, "address_line_2": { "type": [ "string", "null" ], "example": null }, "city": { "type": "string", "example": "Chino" }, "state_code": { "type": "string", "example": "CA" }, "country_code": { "type": "string", "example": "US" }, "postal_code": { "type": "string", "example": "91708" } }, "required": [ "fc_name", "address_line_1", "address_line_2", "city", "state_code", "country_code", "postal_code" ] }, "units": { "type": "integer", "description": "The units Walmart would send to this destination", "example": 5 }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "example": "SKU-06476211912694" }, "gtin": { "type": [ "string", "null" ], "example": "06484856148873" }, "item_qty": { "type": "integer", "example": 5 } }, "required": [ "sku", "gtin", "item_qty" ] } } }, "required": [ "type", "walmart_type", "ship_node", "node_type", "is_sortable", "is_non_sortable", "ship_to_address", "units", "items" ] } }, "its_fees": { "type": "array", "description": "The projected ITS fees, one entry per ITS destination that carries a charge. Empty when Walmart projected none. The ITS fee shape is unverified live: no fee field has come back from Walmart yet (the gate account looks ITS-ineligible), so this follows Walmart's reference documentation.", "items": { "type": "object", "properties": { "ship_node": { "type": [ "string", "null" ], "example": "4093" }, "fc_name": { "type": [ "string", "null" ], "example": "LAX2T" }, "net_transfer_charge_cents": { "type": "integer", "description": "The projected ITS fee for the destination, in cents", "example": 125 }, "currency": { "type": [ "string", "null" ], "example": "USD" }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "example": "SKU-06476211912694" }, "gtin": { "type": [ "string", "null" ], "example": "06484856148873" }, "item_qty": { "type": "integer", "example": 5 }, "net_transfer_charge_cents": { "type": [ "integer", "null" ], "description": "The projected ITS fee for the SKU, in cents", "example": 125 }, "currency": { "type": [ "string", "null" ], "example": "USD" } }, "required": [ "sku", "gtin", "item_qty", "net_transfer_charge_cents", "currency" ] } } }, "required": [ "ship_node", "fc_name", "net_transfer_charge_cents", "currency", "items" ] } } }, "required": [ "destinations", "its_fees" ] } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "destinations": [ { "type": "wfs", "walmart_type": "wfs", "ship_node": "8240", "node_type": "FC", "is_sortable": true, "is_non_sortable": false, "ship_to_address": { "fc_name": "ATL1", "address_line_1": "6055 S Fulton Pkwy", "address_line_2": null, "city": "Atlanta", "state_code": "GA", "country_code": "US", "postal_code": "30349" }, "units": 1, "items": [ { "sku": "CHH2609", "gtin": "00704551260905", "item_qty": 1 } ] } ], "its_fees": [] } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "description": "Not Found — the inbound order does not exist" }, "409": { "$ref": "#/components/schemas/WfsInboundOrderBusy" }, "422": { "description": "The order is not Draft or Rejected, has no items, a SKU in `item_labeling_skus` is not on it, the body is invalid, or Walmart refused the preview (`errors.walmart` carries its codes)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Cannot preview an inbound order unless it is Draft or Rejected." }, "errors": { "type": "object", "description": "A map of field names to arrays of error messages; `walmart` lists Walmart's refusal as `code: description`. Absent when the order's state refused the request." } }, "required": [ "message" ] } } } }, "502": { "description": "The call to Walmart failed or its answer could not be read. Nothing is recorded; preview again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Walmart did not answer, so the result is unknown. Refresh the shipment to see whether Walmart applied the change." }, "errors": { "type": "object", "properties": { "walmart": { "type": "array", "description": "Each error as `: `", "items": { "type": "string" }, "example": [ "504: Gateway Timeout" ] } }, "required": [ "walmart" ] } }, "required": [ "message", "errors" ] } } } } } } }, "/channels/walmart/wfs/inbound-orders/{wfs_inbound_order}/submit": { "post": { "summary": "Submit a WFS inbound order to Walmart", "description": "Queue a draft or rejected inbound order for submission to Walmart. Submission happens in the background, so the returned order is still in its previous status (`draft` or `rejected`); poll the order to see it become `submitted` (with its shipments) or `rejected` (with `errors`). Submitting again while a submission is queued queues nothing more.", "operationId": "submit-wfs-inbound-order", "tags": [ "Channels" ], "parameters": [ { "name": "wfs_inbound_order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The inbound order's uuid", "example": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90" } } ], "responses": { "202": { "description": "The submission was queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WfsInboundOrderDetail" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90", "inbound_order_id": "PO-2026-0042", "channel_id": 1024, "merchant_id": 1042, "status": "draft", "item_count": 1, "unit_count": 120, "shipment_ids": [], "errors": [], "consecutive_failure_count": 0, "submitted_at": null, "rejected_at": null, "cancellation_requested_at": null, "last_reconciled_at": null, "created_at": "2026-09-29T13:58:40Z", "updated_at": "2026-09-29T13:58:40Z", "return_address": { "address_line_1": "100 Main St", "address_line_2": null, "city": "Bentonville", "state_code": "AR", "country_code": "US", "postal_code": "72712" }, "inventory_transfer_service": false, "items": [ { "sku": "SKU-1", "gtin": "00012345678905", "item_description": "Widget", "item_qty": 120, "vendor_pack_qty": 12, "inner_pack_qty": 10, "expected_delivery_date": "2026-10-15", "item_labeling": false } ], "shipments": [], "timeline": [ { "event_uuid": "019b2c4a-1c01-8010-a3f2-6c1d0e9b8a70", "event_type": "item_added", "user_uuid": "019a0f11-2c3d-8001-9e4f-5a6b7c8d9e0f", "shipment_id": null, "details": null, "occurred_at": "2026-09-29T13:58:40Z" }, { "event_uuid": "019b2c4a-1b01-8010-a3f2-6c1d0e9b8a70", "event_type": "drafted", "user_uuid": "019a0f11-2c3d-8001-9e4f-5a6b7c8d9e0f", "shipment_id": null, "details": null, "occurred_at": "2026-09-29T13:58:40Z" } ] } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "409": { "$ref": "#/components/schemas/WfsInboundOrderBusy" }, "422": { "description": "The order is not draft or rejected", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Cannot submit an inbound order unless it is Draft or Rejected." } }, "required": [ "message" ] } } } } } } }, "/channels/walmart/wfs/inbound-orders/{wfs_inbound_order}/cancellation-request": { "post": { "summary": "Request cancellation of a WFS inbound order", "description": "Ask Walmart to cancel a submitted inbound order. Walmart's answer is recorded on the order rather than returned as an error: `timeline[0].event_type` is `cancellation_requested` when Walmart accepted (and `cancellation_requested_at` is set), `cancellation_rejected` when it refused, or `api_error_occurred` when the call failed (see `errors`). The order becomes `cancelled` once Walmart reports it cancelled.", "operationId": "request-wfs-inbound-order-cancellation", "tags": [ "Channels" ], "parameters": [ { "name": "wfs_inbound_order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The inbound order's uuid", "example": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90" } } ], "responses": { "200": { "description": "The inbound order, with the outcome on its timeline", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WfsInboundOrderDetail" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90", "inbound_order_id": "PO-2026-0042", "channel_id": 1024, "merchant_id": 1042, "status": "submitted", "item_count": 1, "unit_count": 120, "shipment_ids": [ "SHP-8812" ], "errors": [], "consecutive_failure_count": 0, "submitted_at": "2026-09-29T14:02:11Z", "rejected_at": null, "cancellation_requested_at": "2026-09-29T16:10:00Z", "last_reconciled_at": "2026-09-29T15:00:03Z", "created_at": "2026-09-29T13:58:40Z", "updated_at": "2026-09-29T16:10:00Z", "return_address": { "address_line_1": "100 Main St", "address_line_2": null, "city": "Bentonville", "state_code": "AR", "country_code": "US", "postal_code": "72712" }, "inventory_transfer_service": false, "items": [ { "sku": "SKU-1", "gtin": "00012345678905", "item_description": "Widget", "item_qty": 120, "vendor_pack_qty": 12, "inner_pack_qty": 10, "expected_delivery_date": "2026-10-15", "item_labeling": false } ], "shipments": [ { "shipment_id": "SHP-8812", "fc_name": "DFW5", "ship_to_address": { "address_line_1": "1 Walmart Way", "address_line_2": null, "city": "Dallas", "state_code": "TX", "country_code": "US", "postal_code": "75201" }, "status": "pending_shipment_details", "expected_delivery_date": "2026-10-15", "updated_expected_delivery_date": null, "actual_delivery_date": null, "requested_units": 120, "received_units": 0, "damaged_units": 0, "carrier_name": null, "tracking_numbers": [], "allocated_at": "2026-09-29T14:02:11Z", "items": [ { "sku": "SKU-1", "gtin": "00012345678905", "requested_qty": 120, "received_qty": 0, "damaged_qty": 0 } ], "carrier_booking": null } ], "timeline": [ { "event_uuid": "019b2c4a-2a01-8010-a3f2-6c1d0e9b8a70", "event_type": "cancellation_requested", "user_uuid": "019a0f11-2c3d-8001-9e4f-5a6b7c8d9e0f", "shipment_id": null, "details": null, "occurred_at": "2026-09-29T16:10:00Z" }, { "event_uuid": "019b2c4a-1d01-8010-a3f2-6c1d0e9b8a70", "event_type": "submitted", "user_uuid": null, "shipment_id": null, "details": null, "occurred_at": "2026-09-29T14:02:11Z" } ] } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "409": { "$ref": "#/components/schemas/WfsInboundOrderBusy" }, "422": { "description": "The order cannot be cancelled: it is not submitted, cancellation was already requested, a shipment is past the point of cancelling, or a carrier booking is unconfirmed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Cannot request cancellation unless the inbound order is Submitted." } }, "required": [ "message" ] } } } } } } }, "/channels/walmart/wfs/inbound-orders/{wfs_inbound_order}/shipments/{shipment}/quantities": { "put": { "summary": "Update a WFS shipment's quantities", "description": "Change how many units of each SKU a shipment will carry. Walmart allows an increase of at most six units per SKU after submission, and a SKU is removed by setting it to 0, but not every SKU on the shipment (that would cancel the whole inbound order); a request outside those rules is refused with 422 before Walmart is called (Walmart remains the authority and may still refuse). The outcome is recorded on the order: `timeline[0].event_type` is `shipment_quantities_updated` when Walmart accepted, `shipment_quantities_rejected` when it refused (also answered 422), or `shipment_quantities_update_unconfirmed` when the call failed (answered 200; the outcome will be learned when the shipment is next refreshed).", "operationId": "update-wfs-shipment-quantities", "tags": [ "Channels" ], "parameters": [ { "name": "wfs_inbound_order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The inbound order's uuid", "example": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90" } }, { "name": "shipment", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{1,32}$", "description": "Walmart's id for a shipment on the order", "example": "SHP-8812" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quantities": { "type": "object", "description": "The new unit quantity for each SKU to change, keyed by SKU. Every SKU must already be on the shipment. Each quantity is 0 (removes the SKU) or between 1 and the SKU's current `requested_qty` plus 6. At least one SKU on the shipment must stay above 0.", "minProperties": 1, "maxProperties": 500, "additionalProperties": { "type": "integer", "minimum": 0 }, "example": { "SKU-1": 96 } } }, "required": [ "quantities" ] } } } }, "responses": { "200": { "description": "The inbound order, with the outcome on its timeline", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WfsInboundOrderDetail" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90", "inbound_order_id": "PO-2026-0042", "channel_id": 1024, "merchant_id": 1042, "status": "submitted", "item_count": 1, "unit_count": 120, "shipment_ids": [ "SHP-8812" ], "errors": [], "consecutive_failure_count": 0, "submitted_at": "2026-09-29T14:02:11Z", "rejected_at": null, "cancellation_requested_at": null, "last_reconciled_at": "2026-09-29T15:00:03Z", "created_at": "2026-09-29T13:58:40Z", "updated_at": "2026-09-29T16:20:00Z", "return_address": { "address_line_1": "100 Main St", "address_line_2": null, "city": "Bentonville", "state_code": "AR", "country_code": "US", "postal_code": "72712" }, "inventory_transfer_service": false, "items": [ { "sku": "SKU-1", "gtin": "00012345678905", "item_description": "Widget", "item_qty": 120, "vendor_pack_qty": 12, "inner_pack_qty": 10, "expected_delivery_date": "2026-10-15", "item_labeling": false } ], "shipments": [ { "shipment_id": "SHP-8812", "fc_name": "DFW5", "ship_to_address": { "address_line_1": "1 Walmart Way", "address_line_2": null, "city": "Dallas", "state_code": "TX", "country_code": "US", "postal_code": "75201" }, "status": "pending_shipment_details", "expected_delivery_date": "2026-10-15", "updated_expected_delivery_date": null, "actual_delivery_date": null, "requested_units": 96, "received_units": 0, "damaged_units": 0, "carrier_name": null, "tracking_numbers": [], "allocated_at": "2026-09-29T14:02:11Z", "items": [ { "sku": "SKU-1", "gtin": "00012345678905", "requested_qty": 96, "received_qty": 0, "damaged_qty": 0 } ], "carrier_booking": null } ], "timeline": [ { "event_uuid": "019b2c4a-3a01-8010-a3f2-6c1d0e9b8a70", "event_type": "shipment_quantities_updated", "user_uuid": "019a0f11-2c3d-8001-9e4f-5a6b7c8d9e0f", "shipment_id": "SHP-8812", "details": null, "occurred_at": "2026-09-29T16:20:00Z" }, { "event_uuid": "019b2c4a-1d01-8010-a3f2-6c1d0e9b8a70", "event_type": "submitted", "user_uuid": null, "shipment_id": null, "details": null, "occurred_at": "2026-09-29T14:02:11Z" } ] } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "409": { "$ref": "#/components/schemas/WfsInboundOrderBusy" }, "422": { "description": "The request failed validation (a quantity above the SKU's current quantity plus 6 is keyed `quantities.` with the message 'Walmart allows at most six more units per SKU; set a SKU to 0 to remove it.'), every SKU on the shipment would be 0 (no `errors`; message 'Set at least one SKU above 0; cancel the order instead.'), the order or shipment cannot take the change (the order is not submitted, the shipment is not on the order, the shipment is already being received or finished, or a SKU is not on the shipment), or Walmart refused the update", "$ref": "#/components/schemas/WfsCarrierCommandRefused" } } } }, "/channels/walmart/wfs/inbound-orders/{wfs_inbound_order}/shipments/{shipment}/tracking": { "post": { "summary": "Submit tracking for a WFS shipment", "description": "Tell Walmart which carrier and tracking numbers a shipment is travelling with. The outcome is recorded on the order: `timeline[0].event_type` is `tracking_submitted` when Walmart accepted (and the shipment shows the carrier and tracking numbers), `tracking_rejected` when it refused, or `api_error_occurred` when the call failed. A Walmart refusal answers 422 and a call Walmart did not answer answers 502.", "operationId": "submit-wfs-shipment-tracking", "tags": [ "Channels" ], "parameters": [ { "name": "wfs_inbound_order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The inbound order's uuid", "example": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90" } }, { "name": "shipment", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{1,32}$", "description": "Walmart's id for a shipment on the order", "example": "SHP-8812" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "carrier_name": { "type": "string", "minLength": 1, "maxLength": 100, "example": "UPS" }, "tracking_numbers": { "type": "array", "description": "Each number at most once", "minItems": 1, "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": [ "1Z999AA10123456784", "1Z999AA10123456785" ] } }, "required": [ "carrier_name", "tracking_numbers" ] } } } }, "responses": { "200": { "description": "The inbound order, with the outcome on its timeline", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WfsInboundOrderDetail" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90", "inbound_order_id": "PO-2026-0042", "channel_id": 1024, "merchant_id": 1042, "status": "submitted", "item_count": 1, "unit_count": 120, "shipment_ids": [ "SHP-8812" ], "errors": [], "consecutive_failure_count": 0, "submitted_at": "2026-09-29T14:02:11Z", "rejected_at": null, "cancellation_requested_at": null, "last_reconciled_at": "2026-09-29T15:00:03Z", "created_at": "2026-09-29T13:58:40Z", "updated_at": "2026-09-29T16:30:00Z", "return_address": { "address_line_1": "100 Main St", "address_line_2": null, "city": "Bentonville", "state_code": "AR", "country_code": "US", "postal_code": "72712" }, "inventory_transfer_service": false, "items": [ { "sku": "SKU-1", "gtin": "00012345678905", "item_description": "Widget", "item_qty": 120, "vendor_pack_qty": 12, "inner_pack_qty": 10, "expected_delivery_date": "2026-10-15", "item_labeling": false } ], "shipments": [ { "shipment_id": "SHP-8812", "fc_name": "DFW5", "ship_to_address": { "address_line_1": "1 Walmart Way", "address_line_2": null, "city": "Dallas", "state_code": "TX", "country_code": "US", "postal_code": "75201" }, "status": "pending_shipment_details", "expected_delivery_date": "2026-10-15", "updated_expected_delivery_date": null, "actual_delivery_date": null, "requested_units": 120, "received_units": 0, "damaged_units": 0, "carrier_name": "UPS", "tracking_numbers": [ "1Z999AA10123456784", "1Z999AA10123456785" ], "allocated_at": "2026-09-29T14:02:11Z", "items": [ { "sku": "SKU-1", "gtin": "00012345678905", "requested_qty": 120, "received_qty": 0, "damaged_qty": 0 } ], "carrier_booking": null } ], "timeline": [ { "event_uuid": "019b2c4a-4a01-8010-a3f2-6c1d0e9b8a70", "event_type": "tracking_submitted", "user_uuid": "019a0f11-2c3d-8001-9e4f-5a6b7c8d9e0f", "shipment_id": "SHP-8812", "details": null, "occurred_at": "2026-09-29T16:30:00Z" }, { "event_uuid": "019b2c4a-1d01-8010-a3f2-6c1d0e9b8a70", "event_type": "submitted", "user_uuid": null, "shipment_id": null, "details": null, "occurred_at": "2026-09-29T14:02:11Z" } ] } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "409": { "$ref": "#/components/schemas/WfsInboundOrderBusy" }, "422": { "description": "The request failed validation, the order or shipment cannot take tracking (the order is not submitted, the shipment is not on the order, the shipment is finished, or a tracking number is repeated), or Walmart refused the tracking", "$ref": "#/components/schemas/WfsCarrierCommandRefused" }, "502": { "$ref": "#/components/schemas/WfsCarrierCommandFailed" } } } }, "/channels/walmart/wfs/inbound-orders/{wfs_inbound_order}/shipments/{shipment}/box-label": { "post": { "summary": "Create a WFS shipment box label", "description": "Have Walmart create the box labels for a shipment and download them. The file is returned as Walmart produced it and is not stored.", "operationId": "create-wfs-shipment-box-label", "tags": [ "Channels" ], "parameters": [ { "name": "wfs_inbound_order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The inbound order's uuid", "example": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90" } }, { "name": "shipment", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{1,32}$", "description": "Walmart's id for a shipment on the order", "example": "SHP-8812" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "label_size": { "type": [ "string", "null" ], "description": "The label size. Walmart's default when omitted.", "enum": [ "X4_6", "X4_3", null ], "example": "X4_6" }, "label_format": { "type": [ "string", "null" ], "description": "The file format. Walmart's default when omitted.", "enum": [ "PDF", "ZPL", null ], "example": "PDF" }, "load_types": { "type": [ "array", "null" ], "description": "How many labels to create for each kind of load", "items": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 1, "example": 3 }, "load_type": { "type": "string", "enum": [ "SINGLE SKU", "PALLET", "MIXED SKUS" ], "example": "SINGLE SKU" } }, "required": [ "count", "load_type" ] } } } } } } }, "responses": { "200": { "description": "The label file, with Walmart's `Content-Type` and `Content-Disposition: attachment; filename=\"wfs-box-label-.\"`", "headers": { "Content-Disposition": { "schema": { "type": "string", "example": "attachment; filename=\"wfs-box-label-SHP-8812.pdf\"" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/zpl": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "description": "Not Found — the inbound order does not exist, or the shipment is not on it" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" }, "502": { "description": "Walmart could not create the label", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Walmart could not create the box label." }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "ERR_1" }, "message": { "type": "string", "example": "Shipment not found." }, "details": { "type": "string", "example": "shipmentId" } }, "required": [ "code", "message", "details" ] } } }, "required": [ "message", "errors" ] } } } } } } }, "/channels/walmart/wfs/inbound-orders/{wfs_inbound_order}/shipments/{shipment}/rate-quotes": { "get": { "summary": "List the rate quotes of a WFS shipment", "description": "The Walmart preferred-carrier quotes requested for a shipment, newest first, at most 200.", "operationId": "index-wfs-shipment-rate-quotes", "tags": [ "Channels" ], "parameters": [ { "name": "wfs_inbound_order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The inbound order's uuid", "example": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90" } }, { "name": "shipment", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{1,32}$", "description": "Walmart's id for a shipment on the order", "example": "SHP-8812" } } ], "responses": { "200": { "description": "The shipment's quotes", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WfsRateQuote" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "description": "Not Found — the inbound order does not exist, or the shipment is not on it" } } }, "post": { "summary": "Request rate quotes for a WFS shipment", "description": "Ask Walmart's preferred-carrier programme for quotes. The fields besides `quote_type` and `ship_from` depend on the quote type. The returned quotes are kept and can be booked with the carrier booking endpoint.", "operationId": "request-wfs-shipment-rate-quotes", "tags": [ "Channels" ], "parameters": [ { "name": "wfs_inbound_order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The inbound order's uuid", "example": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90" } }, { "name": "shipment", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{1,32}$", "description": "Walmart's id for a shipment on the order", "example": "SHP-8812" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote_type": { "type": "string", "enum": [ "Parcel", "LTL", "FTL" ], "example": "Parcel" }, "ship_from": { "type": "object", "description": "The address the carrier collects from", "properties": { "address_line_1": { "type": "string", "maxLength": 255, "example": "1 Warehouse Way" }, "address_line_2": { "type": [ "string", "null" ], "maxLength": 255 }, "city": { "type": "string", "maxLength": 255, "example": "Sunnyvale" }, "state_code": { "type": "string", "maxLength": 10, "example": "CA" }, "country_code": { "type": "string", "minLength": 2, "example": "US" }, "postal_code": { "type": "string", "maxLength": 20, "example": "95126" }, "phone": { "type": [ "string", "null" ], "maxLength": 30, "example": "5550100" }, "location_name": { "type": [ "string", "null" ], "maxLength": 255, "example": "Main warehouse" } }, "required": [ "address_line_1", "city", "state_code", "country_code", "postal_code" ] }, "packages": { "type": [ "array", "null" ], "description": "The boxes to ship. Required for `Parcel`.", "minItems": 1, "maxItems": 500, "items": { "type": "object", "properties": { "sequence_number": { "type": "integer", "minimum": 1, "example": 1 }, "weight_lb": { "type": "number", "minimum": 0, "example": 12.5 }, "length_in": { "type": "number", "minimum": 0, "example": 16 }, "width_in": { "type": "number", "minimum": 0, "example": 12 }, "height_in": { "type": "number", "minimum": 0, "example": 10 }, "package_type": { "type": "string", "maxLength": 50, "example": "MIXED SKUS" }, "is_stackable": { "type": [ "boolean", "null" ], "example": true }, "package_count": { "type": [ "integer", "null" ], "minimum": 1 } }, "required": [ "sequence_number", "weight_lb", "length_in", "width_in", "height_in", "package_type" ] } }, "pickup_from": { "type": [ "string", "null" ], "format": "date-time", "description": "Earliest pickup. Required for `LTL` and `FTL`. An ISO 8601 timestamp in UTC or with an offset, e.g. `2026-10-06T08:00:00Z`", "example": "2026-10-06T08:00:00Z" }, "pickup_to": { "type": [ "string", "null" ], "format": "date-time", "description": "Latest pickup, after `pickup_from`. Required for `LTL` and `FTL`.", "example": "2026-10-07T17:00:00Z" }, "freight": { "type": [ "object", "null" ], "description": "Freight details. Required for `LTL` and `FTL`.", "properties": { "freight_class": { "type": [ "number", "null" ], "minimum": 0, "example": 70 }, "declared_value": { "type": [ "number", "null" ], "minimum": 0 }, "single_sku_boxes": { "type": "integer", "minimum": 0, "example": 0 }, "mixed_sku_boxes": { "type": "integer", "minimum": 0, "example": 12 }, "total_pallet_count": { "type": "integer", "minimum": 0, "example": 1 } }, "required": [ "single_sku_boxes", "mixed_sku_boxes", "total_pallet_count" ] }, "pallets": { "type": [ "array", "null" ], "description": "The pallets to ship. Required for `LTL` and `FTL`.", "minItems": 1, "maxItems": 500, "items": { "type": "object", "properties": { "sequence_number": { "type": "integer", "minimum": 1, "example": 1 }, "weight_lb": { "type": "number", "minimum": 0, "example": 12.5 }, "length_in": { "type": "number", "minimum": 0, "example": 16 }, "width_in": { "type": "number", "minimum": 0, "example": 12 }, "height_in": { "type": "number", "minimum": 0, "example": 10 }, "package_type": { "type": "string", "maxLength": 50, "example": "MIXED SKUS" }, "is_stackable": { "type": [ "boolean", "null" ], "example": true }, "package_count": { "type": [ "integer", "null" ], "minimum": 1 } }, "required": [ "sequence_number", "weight_lb", "length_in", "width_in", "height_in", "package_type" ] } }, "equipment": { "type": [ "array", "null" ], "description": "The truck equipment. Required for `FTL`.", "minItems": 1, "maxItems": 10, "items": { "type": "object", "properties": { "length_ft": { "type": "integer", "minimum": 1, "example": 53 }, "protection_level": { "type": "string", "maxLength": 50, "example": "Dry" }, "type": { "type": "string", "maxLength": 50, "example": "VAN53" } }, "required": [ "length_ft", "protection_level", "type" ] } }, "mode": { "type": [ "string", "null" ], "maxLength": 50, "description": "Required for `FTL`", "example": "FTL" }, "service_level": { "type": [ "string", "null" ], "maxLength": 50, "description": "Required for `FTL`", "example": "WFS" } }, "required": [ "quote_type", "ship_from" ] } } } }, "responses": { "200": { "description": "The quotes Walmart returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WfsRateQuote" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "description": "Not Found — the inbound order does not exist, or the shipment is not on it" }, "422": { "description": "The request failed validation, or Walmart did not return a quote. A Walmart rejection and a failed call look the same.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Walmart did not return a quote" }, "errors": { "type": "object", "description": "A map of keys to lists of messages. Validation failures are keyed by field; Walmart's errors are under `walmart`, each as `: `.", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "walmart": [ "400.WFS.100: PO details not found" ] } } }, "required": [ "message", "errors" ] } } } } } } }, "/channels/walmart/wfs/inbound-orders/{wfs_inbound_order}/shipments/{shipment}/carrier-booking": { "post": { "summary": "Book a carrier for a WFS shipment", "description": "Book one of the shipment's rate quotes. The quote's type decides which fields are required. Walmart's answer is recorded on the order: `timeline[0].event_type` is `carrier_booked`, `carrier_booking_rejected`, `carrier_booking_unconfirmed` or `api_error_occurred`. A Walmart refusal answers 422 and a call Walmart did not answer answers 502; an unconfirmed booking answers 200 with `carrier_booking.state` `unconfirmed`.", "operationId": "book-wfs-shipment-carrier", "tags": [ "Channels" ], "parameters": [ { "name": "wfs_inbound_order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The inbound order's uuid", "example": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90" } }, { "name": "shipment", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{1,32}$", "description": "Walmart's id for a shipment on the order", "example": "SHP-8812" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "The fields besides `rate_quote_uuid` and the box counts depend on the quote's type.", "properties": { "rate_quote_uuid": { "type": "string", "format": "uuid", "description": "A quote of this shipment", "example": "019b2c52-3f10-7c4e-8a1d-2b3c4d5e6f70" }, "single_sku_boxes": { "type": "integer", "minimum": 0, "example": 2 }, "mixed_sku_boxes": { "type": "integer", "minimum": 0, "example": 0 }, "business_location_name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Required for `LTL` and `FTL`", "example": "Main warehouse" }, "pickup_instruction": { "type": [ "string", "null" ], "maxLength": 500 }, "pickup_dates": { "type": [ "array", "null" ], "description": "Preferred pickup dates. Required for `LTL`.", "minItems": 1, "maxItems": 10, "items": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "`YYYY-MM-DD`", "example": "2026-10-06" }, "ready_time": { "type": "string", "pattern": "^\\d{2}:\\d{2}:\\d{2}$", "description": "`HH:MM:SS`", "example": "08:00:00" }, "close_time": { "type": "string", "pattern": "^\\d{2}:\\d{2}:\\d{2}$", "description": "`HH:MM:SS`", "example": "17:00:00" }, "priority": { "type": [ "integer", "null" ], "minimum": 1, "description": "Defaults to the date's position in the list, starting at 1", "example": 1 } }, "required": [ "date", "ready_time", "close_time" ] } }, "shipper": { "type": [ "object", "null" ], "description": "Who the carrier contacts at pickup. Required for `LTL` and `FTL`.", "properties": { "name": { "type": "string", "maxLength": 255, "example": "Ada Lovelace" }, "first_name": { "type": "string", "maxLength": 100, "example": "Ada" }, "last_name": { "type": "string", "maxLength": 100, "example": "Lovelace" }, "phone": { "type": "string", "maxLength": 30, "example": "5550100" }, "email": { "type": "string", "format": "email", "maxLength": 255, "example": "ada@example.com" } }, "required": [ "name", "first_name", "last_name", "phone", "email" ] }, "ship_from": { "type": [ "object", "null" ], "description": "The address the carrier collects from. Required for `LTL` and `FTL`.", "properties": { "address_line_1": { "type": "string", "maxLength": 255, "example": "1 Warehouse Way" }, "address_line_2": { "type": [ "string", "null" ], "maxLength": 255 }, "city": { "type": "string", "maxLength": 255, "example": "Sunnyvale" }, "state_code": { "type": "string", "maxLength": 10, "example": "CA" }, "country_code": { "type": "string", "minLength": 2, "example": "US" }, "postal_code": { "type": "string", "maxLength": 20, "example": "95126" }, "phone": { "type": [ "string", "null" ], "maxLength": 30, "example": "5550100" }, "location_name": { "type": [ "string", "null" ], "maxLength": 255, "example": "Main warehouse" } }, "required": [ "address_line_1", "city", "state_code", "country_code", "postal_code" ] }, "operation_hours": { "type": [ "array", "null" ], "description": "The pickup location's opening hours by weekday. Walmart requires them for LTL and FTL bookings: at least three days, including every preferred pickup date (`pickup_dates`; for FTL, every day from `schedule.min_pickup_at` to `schedule.max_pickup_at`); a booking without them is refused with 'At least 3 days of operation hours must be provided, including the preferred pickup date.' Times as `HH:MM:SS`.", "maxItems": 7, "items": { "type": "object", "properties": { "day_of_week_code": { "type": "integer", "minimum": 0, "maximum": 7, "description": "The day of the week, as Walmart defines it", "example": 1 }, "open_time": { "type": "string", "maxLength": 10, "example": "09:00:00" }, "close_time": { "type": "string", "maxLength": 10, "example": "17:00:00" } }, "required": [ "day_of_week_code", "open_time", "close_time" ] } }, "declared_value": { "type": [ "number", "null" ], "minimum": 0 }, "total_pallet_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Required for `LTL`", "example": 1 }, "pallets": { "type": [ "array", "null" ], "description": "The pallets. Required for `LTL` and `FTL`.", "minItems": 1, "maxItems": 500, "items": { "type": "object", "properties": { "sequence_number": { "type": "integer", "minimum": 1, "example": 1 }, "weight_lb": { "type": "number", "minimum": 0, "example": 12.5 }, "length_in": { "type": "number", "minimum": 0, "example": 16 }, "width_in": { "type": "number", "minimum": 0, "example": 12 }, "height_in": { "type": "number", "minimum": 0, "example": 10 }, "package_type": { "type": "string", "maxLength": 50, "example": "MIXED SKUS" }, "is_stackable": { "type": [ "boolean", "null" ], "example": true }, "package_count": { "type": [ "integer", "null" ], "minimum": 1 } }, "required": [ "sequence_number", "weight_lb", "length_in", "width_in", "height_in", "package_type" ] } }, "pickup_window": { "type": [ "string", "null" ], "maxLength": 100, "description": "Required for `FTL`", "example": "08:00-17:00" }, "schedule": { "type": [ "object", "null" ], "description": "The FTL pickup and delivery window. Required for `FTL`.", "properties": { "min_pickup_at": { "type": "string", "format": "date-time", "example": "2026-10-06T08:00:00Z" }, "max_pickup_at": { "type": "string", "format": "date-time", "example": "2026-10-06T17:00:00Z" }, "min_due_at": { "type": "string", "format": "date-time", "example": "2026-10-08T08:00:00Z" }, "max_due_at": { "type": "string", "format": "date-time", "example": "2026-10-09T17:00:00Z" } }, "required": [ "min_pickup_at", "max_pickup_at", "min_due_at", "max_due_at" ] }, "equipment_code": { "type": [ "string", "null" ], "maxLength": 50, "description": "Required for `FTL`", "example": "VAN53" }, "equipment_type": { "type": [ "string", "null" ], "maxLength": 50, "description": "Required for `FTL`", "example": "Dry" }, "equipment_length_ft": { "type": [ "number", "null" ], "minimum": 0, "description": "Required for `FTL`", "example": 53 }, "protection_level": { "type": [ "string", "null" ], "maxLength": 50, "description": "Required for `FTL`", "example": "Dry" } }, "required": [ "rate_quote_uuid", "single_sku_boxes", "mixed_sku_boxes" ] } } } }, "responses": { "200": { "description": "The inbound order, with the outcome on its timeline and the booking on the shipment", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WfsInboundOrderDetail" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "description": "Not Found — the inbound order does not exist, the shipment is not on it, or the quote is not one of the shipment's" }, "409": { "$ref": "#/components/schemas/WfsInboundOrderBusy" }, "422": { "description": "The request failed validation, the rate quote has already been booked (`selected_at` is set), the order or shipment cannot be booked (the order is not submitted, the shipment is finished, or it already has a live or unconfirmed booking), or Walmart refused the booking", "$ref": "#/components/schemas/WfsCarrierCommandRefused" }, "502": { "$ref": "#/components/schemas/WfsCarrierCommandFailed" } } }, "delete": { "summary": "Cancel the carrier booking of a WFS shipment", "description": "Cancel the shipment's live booking. Walmart's answer is recorded on the order: `timeline[0].event_type` is `carrier_booking_cancelled`, `carrier_booking_cancellation_rejected` or `api_error_occurred`. A Walmart refusal answers 422 and a call Walmart did not answer answers 502.", "operationId": "cancel-wfs-shipment-carrier-booking", "tags": [ "Channels" ], "parameters": [ { "name": "wfs_inbound_order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The inbound order's uuid", "example": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90" } }, { "name": "shipment", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{1,32}$", "description": "Walmart's id for a shipment on the order", "example": "SHP-8812" } } ], "responses": { "200": { "description": "The inbound order, with the outcome on its timeline", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WfsInboundOrderDetail" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "description": "Not Found — the inbound order does not exist, or the shipment is not on it" }, "409": { "$ref": "#/components/schemas/WfsInboundOrderBusy" }, "422": { "description": "The order is not submitted, the shipment has no live booking, or Walmart refused the cancellation", "$ref": "#/components/schemas/WfsCarrierCommandRefused" }, "502": { "$ref": "#/components/schemas/WfsCarrierCommandFailed" } } } }, "/channels/walmart/wfs/inbound-orders/{wfs_inbound_order}/shipments/{shipment}/carrier-label": { "post": { "summary": "Generate the carrier label of a WFS shipment", "description": "Ask Walmart to generate the carrier label for a Parcel booking. Walmart generates it asynchronously; fetch it with `GET` on the same path. The outcome is recorded on the order: `timeline[0].event_type` is `carrier_label_generated`, `carrier_label_rejected` or `api_error_occurred`. A Walmart refusal answers 422 and a call Walmart did not answer answers 502.", "operationId": "generate-wfs-shipment-carrier-label", "tags": [ "Channels" ], "parameters": [ { "name": "wfs_inbound_order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The inbound order's uuid", "example": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90" } }, { "name": "shipment", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{1,32}$", "description": "Walmart's id for a shipment on the order", "example": "SHP-8812" } } ], "responses": { "202": { "description": "The inbound order; `carrier_booking.label_generated_at` and `ship_date` show once Walmart accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WfsInboundOrderDetail" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "description": "Not Found — the inbound order does not exist, or the shipment is not on it" }, "409": { "$ref": "#/components/schemas/WfsInboundOrderBusy" }, "422": { "description": "The request failed validation, the shipment has no live Parcel booking, or Walmart refused the label", "$ref": "#/components/schemas/WfsCarrierCommandRefused" }, "502": { "$ref": "#/components/schemas/WfsCarrierCommandFailed" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ship_date": { "type": [ "string", "null" ], "description": "When the parcels ship, as `YYYY-MM-DD` or an ISO 8601 timestamp", "example": "2026-10-06" } } } } } } }, "get": { "summary": "Download the carrier label of a WFS shipment", "description": "Download the carrier label of the shipment's live Parcel booking. The file is returned as Walmart produced it and is not stored.", "operationId": "download-wfs-shipment-carrier-label", "tags": [ "Channels" ], "parameters": [ { "name": "wfs_inbound_order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The inbound order's uuid", "example": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90" } }, { "name": "shipment", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{1,32}$", "description": "Walmart's id for a shipment on the order", "example": "SHP-8812" } }, { "name": "label_size", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "X4_6", "X4_3" ], "default": "X4_6", "example": "X4_6" } } ], "responses": { "200": { "description": "The label file, with Walmart's `Content-Type`", "headers": { "Content-Disposition": { "description": "The filename ends in `.zpl` for an `application/zpl` label and `.pdf` otherwise", "schema": { "type": "string", "example": "attachment; filename=\"wfs-carrier-label-SHP-8812.pdf\"" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/zpl": { "schema": { "type": "string", "format": "binary" } } } }, "202": { "description": "Walmart is still generating the label (about a minute after generation). Empty body; retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer", "example": 30 } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "description": "Not Found — the inbound order does not exist, or the shipment is not on it" }, "422": { "description": "The query failed validation, or the shipment has no live Parcel booking", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Shipment 'SHP-8812' has no live Parcel carrier booking." }, "errors": { "type": "object", "description": "A map of field names to arrays of error messages. Absent when the order's or booking's state refused the request." } }, "required": [ "message" ] } } } }, "502": { "description": "Walmart could not answer; `errors` carries its codes", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Walmart could not return the carrier label." }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string", "example": "Shipment not found." }, "details": { "type": "string", "example": "shipmentId" } }, "required": [ "code", "message", "details" ] } } }, "required": [ "message", "errors" ] } } } } } } }, "/channels/walmart/wfs/inbound-orders/{wfs_inbound_order}/shipments/{shipment}/bill-of-lading": { "get": { "summary": "Print the bill of lading of a WFS shipment", "description": "Download the bill of lading of the shipment's live LTL booking. The file is returned as Walmart produced it and is not stored.", "operationId": "print-wfs-shipment-bill-of-lading", "tags": [ "Channels" ], "parameters": [ { "name": "wfs_inbound_order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The inbound order's uuid", "example": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90" } }, { "name": "shipment", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{1,32}$", "description": "Walmart's id for a shipment on the order", "example": "SHP-8812" } } ], "responses": { "200": { "description": "The bill of lading, with Walmart's `Content-Type`", "headers": { "Content-Disposition": { "schema": { "type": "string", "example": "attachment; filename=\"wfs-bol-SHP-8812.pdf\"" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "description": "Not Found — the inbound order does not exist, or the shipment is not on it" }, "422": { "description": "The shipment has no live LTL booking", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Shipment 'SHP-8812' has no live LTL carrier booking." }, "errors": { "type": "object", "description": "A map of field names to arrays of error messages. Absent when the order's or booking's state refused the request." } }, "required": [ "message" ] } } } }, "502": { "description": "Walmart could not answer; `errors` carries its codes", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Walmart could not return the bill of lading." }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string", "example": "Shipment not found." }, "details": { "type": "string", "example": "shipmentId" } }, "required": [ "code", "message", "details" ] } } }, "required": [ "message", "errors" ] } } } } } } }, "/channels/walmart/wfs/inbound-orders/{wfs_inbound_order}/shipments/{shipment}/carrier-tracking": { "get": { "summary": "Read the carrier tracking of a WFS shipment", "description": "Walmart's carrier tracking for the shipment's live booking, read in the booking's mode. Nothing is stored.", "operationId": "index-wfs-shipment-carrier-tracking", "tags": [ "Channels" ], "parameters": [ { "name": "wfs_inbound_order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The inbound order's uuid", "example": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90" } }, { "name": "shipment", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{1,32}$", "description": "Walmart's id for a shipment on the order", "example": "SHP-8812" } } ], "responses": { "200": { "description": "The tracking entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "A carrier tracking entry for a shipment, as Walmart reports it", "properties": { "shipment_id": { "type": "string", "example": "SHP-8812" }, "tracking_no": { "type": "string", "example": "PRO-123" }, "status": { "type": [ "string", "null" ], "example": "IN_TRANSIT" }, "carrier_name": { "type": [ "string", "null" ], "example": "Old Dominion" }, "is_master": { "type": [ "boolean", "null" ], "description": "The master tracking number; the others are per package", "example": true }, "current_location": { "type": [ "string", "null" ], "example": "Dallas, TX" }, "estimated_delivery_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-08T17:00:00Z" }, "actual_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "pro_number": { "type": [ "string", "null" ], "example": "PRO-123" }, "event_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-06T12:30:00Z" }, "mode": { "type": [ "string", "null" ], "example": "LTL" }, "event_time_zone": { "type": [ "string", "null" ], "example": "CST" } }, "required": [ "shipment_id", "tracking_no", "status", "carrier_name", "is_master", "current_location", "estimated_delivery_at", "actual_delivery_at", "pro_number", "event_at", "mode", "event_time_zone" ] } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "description": "Not Found — the inbound order does not exist, or the shipment is not on it" }, "422": { "description": "The shipment has no live booking", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Shipment 'SHP-8812' has no live carrier booking." }, "errors": { "type": "object", "description": "A map of field names to arrays of error messages. Absent when the order's or booking's state refused the request." } }, "required": [ "message" ] } } } }, "502": { "description": "Walmart could not answer; `errors` carries its codes", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Walmart could not return the carrier tracking." }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "INVALID_REQUEST" }, "message": { "type": "string", "example": "Shipment not found." }, "details": { "type": "string", "example": "shipmentId" } }, "required": [ "code", "message", "details" ] } } }, "required": [ "message", "errors" ] } } } } } } }, "/channels/walmart/wfs/inbound-orders/{wfs_inbound_order}/shipments/{shipment}/pickup": { "put": { "summary": "Reschedule the pickup of a WFS shipment", "description": "Ask Walmart to move the pickup of the shipment's live LTL booking. The booked quote is used. The outcome is recorded on the order: `timeline[0].event_type` is `pickup_rescheduled`, `pickup_reschedule_rejected` or `api_error_occurred`. A Walmart refusal answers 422 and a call Walmart did not answer answers 502.", "operationId": "reschedule-wfs-shipment-pickup", "tags": [ "Channels" ], "parameters": [ { "name": "wfs_inbound_order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The inbound order's uuid", "example": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90" } }, { "name": "shipment", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{1,32}$", "description": "Walmart's id for a shipment on the order", "example": "SHP-8812" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pickup_dates": { "type": "array", "description": "The requested pickup dates, in order of preference", "minItems": 1, "maxItems": 10, "items": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "`YYYY-MM-DD`", "example": "2026-10-06" }, "ready_time": { "type": "string", "pattern": "^\\d{2}:\\d{2}:\\d{2}$", "description": "`HH:MM:SS`", "example": "08:00:00" }, "close_time": { "type": "string", "pattern": "^\\d{2}:\\d{2}:\\d{2}$", "description": "`HH:MM:SS`", "example": "17:00:00" }, "priority": { "type": [ "integer", "null" ], "minimum": 1, "description": "Defaults to the date's position in the list, starting at 1", "example": 1 } }, "required": [ "date", "ready_time", "close_time" ] } }, "contact": { "type": "object", "description": "Who the carrier contacts at pickup", "properties": { "first_name": { "type": "string", "maxLength": 100, "example": "Ada" }, "last_name": { "type": "string", "maxLength": 100, "example": "Lovelace" }, "email": { "type": "string", "format": "email", "maxLength": 255, "example": "ada@example.com" }, "secondary_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "area_code": { "type": [ "string", "null" ], "maxLength": 10, "example": "555" }, "number": { "type": "string", "maxLength": 30, "example": "0100" }, "extension": { "type": [ "string", "null" ], "maxLength": 10 } }, "required": [ "first_name", "last_name", "email", "number" ] }, "ship_from": { "type": [ "object", "null" ], "description": "A new pickup address, if it changed", "properties": { "address_line_1": { "type": "string", "maxLength": 255, "example": "1 Warehouse Way" }, "address_line_2": { "type": [ "string", "null" ], "maxLength": 255 }, "city": { "type": "string", "maxLength": 255, "example": "Sunnyvale" }, "state_code": { "type": "string", "maxLength": 10, "example": "CA" }, "country_code": { "type": "string", "minLength": 2, "example": "US" }, "postal_code": { "type": "string", "maxLength": 20, "example": "95126" }, "phone": { "type": [ "string", "null" ], "maxLength": 30, "example": "5550100" }, "location_name": { "type": [ "string", "null" ], "maxLength": 255, "example": "Main warehouse" } }, "required": [ "address_line_1", "city", "state_code", "country_code", "postal_code" ] }, "carrier": { "type": [ "string", "null" ], "maxLength": 100, "example": "ODFL" } }, "required": [ "pickup_dates", "contact" ] } } } }, "responses": { "200": { "description": "The inbound order; the pickup shows on `carrier_booking.pickup`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WfsInboundOrderDetail" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "description": "Not Found — the inbound order does not exist, or the shipment is not on it" }, "409": { "$ref": "#/components/schemas/WfsInboundOrderBusy" }, "422": { "description": "The request failed validation, the shipment has no live LTL booking, or Walmart refused the reschedule", "$ref": "#/components/schemas/WfsCarrierCommandRefused" }, "502": { "$ref": "#/components/schemas/WfsCarrierCommandFailed" } } } }, "/channels/walmart/wfs/inbound-orders/{wfs_inbound_order}/shipments/{shipment}/pickup/refresh": { "post": { "summary": "Refresh the pickup of a WFS shipment", "description": "Read the pickup Walmart scheduled for the shipment's live LTL booking and record it on the order when it changed.", "operationId": "refresh-wfs-shipment-pickup", "tags": [ "Channels" ], "parameters": [ { "name": "wfs_inbound_order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The inbound order's uuid", "example": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90" } }, { "name": "shipment", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{1,32}$", "description": "Walmart's id for a shipment on the order", "example": "SHP-8812" } } ], "responses": { "200": { "description": "The inbound order; the pickup shows on `carrier_booking.pickup`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WfsInboundOrderDetail" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "description": "Not Found — the inbound order does not exist, or the shipment is not on it" }, "409": { "$ref": "#/components/schemas/WfsInboundOrderBusy" }, "422": { "description": "The order is not submitted, or the shipment has no live LTL booking", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Shipment 'SHP-8812' has no live LTL carrier booking." }, "errors": { "type": "object", "description": "A map of field names to arrays of error messages. Absent when the order's or booking's state refused the request." } }, "required": [ "message" ] } } } } } } }, "/billing/charges": { "get": { "summary": "List charges", "operationId": "list-charges", "tags": [ "Billing" ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search language filter. Supported fields: `category` (string), `description` (string), `invoice` (null check, use `invoice^\"null\"` or `invoice!^\"null\"`), `voided_at` (null check, use `voided_at^\"null\"` or `voided_at!^\"null\"`), `created_at` (date, requires the `$DATE` modifier and supports the `:`, `>`, `>=`, `<`, `<=` operators with a `YYYY-MM-DD` value). Clauses can be combined with `AND` / `OR`. Example: `created_at$DATE>=\"2026-01-15\"`", "example": "created_at$DATE>=\"2026-01-15\"" }, { "name": "page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Page" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PerPage" } } ], "responses": { "200": { "description": "A successful response returning the paginated list of charges", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/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, "invoice_id": 133, "stripe_invoice_item_id": null } ], "total": 11, "current_page": 1, "last_page": 2, "per_page": 10, "from": 0, "to": 10 } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } } }, "/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": { "$ref": "#/components/schemas/Charge" }, "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, "invoice_id": null, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } } } }, "/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": "#/components/schemas/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, "invoice_id": null, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/billing/invoices": { "get": { "summary": "List invoices", "operationId": "list-invoices", "tags": [ "Billing" ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search language filter. Supported fields: `id` (integer), `stripe_invoice_id` (string), `created_at` (date, requires the `$DATE` modifier and supports the `:`, `>`, `>=`, `<`, `<=` operators with a `YYYY-MM-DD` value). Clauses can be combined with `AND` / `OR`. Example: `created_at$DATE>=\"2026-01-15\"`", "example": "created_at$DATE>=\"2026-01-15\"" }, { "name": "page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Page" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PerPage" } } ], "responses": { "200": { "description": "A successful response returning the paginated list of invoices", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } }, "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": { "$ref": "#/components/schemas/Invoice" }, "invoices": { "type": "array", "description": "All draft invoices created by the request. When more than 250 charges are invoiced, charges are split across multiple draft invoices.", "items": { "$ref": "#/components/schemas/Invoice" } } }, "required": [ "message", "invoice", "invoices" ] }, "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 } }, "invoices": [ { "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/billing/invoices/{invoice}/collect": { "post": { "summary": "Collect payment for an invoice", "description": "Triggers an immediate charge attempt against the merchant's payment method 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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/billing/receivables": { "get": { "summary": "List merchant receivables", "operationId": "list-receivables", "description": "Returns receivables totals aggregated per merchant for the current service provider: open charges, draft invoices, and unpaid invoices, each as a count and a total amount. When a merchant is selected in the request context, only that merchant's totals are returned.", "tags": [ "Billing" ], "responses": { "200": { "description": "A successful response returning the receivables totals for each merchant", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "merchant_id": { "type": "integer", "description": "The ID of the merchant the receivables totals belong to", "example": 6320 }, "open_charges_count": { "type": "integer", "description": "Number of open charges (not voided and not yet attached to an invoice)", "example": 3 }, "open_charges_amount": { "type": "string", "description": "Total amount of open charges, serialized as a fixed-point decimal string with six fractional digits", "example": "521.000000" }, "draft_invoices_count": { "type": "integer", "description": "Number of draft invoices (not voided and not yet finalized)", "example": 2 }, "draft_invoices_amount": { "type": "string", "description": "Total amount of draft invoices, serialized as a fixed-point decimal string with six fractional digits", "example": "257.750000" }, "unpaid_invoices_count": { "type": "integer", "description": "Number of unpaid invoices (not voided, finalized, and not marked paid in Stripe)", "example": 1 }, "unpaid_invoices_amount": { "type": "string", "description": "Total amount of unpaid invoices, serialized as a fixed-point decimal string with six fractional digits", "example": "99.990000" }, "billing_currency": { "type": "string", "description": "The ISO 4217 currency code the receivables totals are denominated in", "example": "USD" } }, "additionalProperties": false, "required": [ "merchant_id", "open_charges_count", "open_charges_amount", "draft_invoices_count", "draft_invoices_amount", "unpaid_invoices_count", "unpaid_invoices_amount", "billing_currency" ] } }, "examples": { "example": { "value": [ { "merchant_id": 6320, "open_charges_count": 3, "open_charges_amount": "521.000000", "draft_invoices_count": 0, "draft_invoices_amount": "0.000000", "unpaid_invoices_count": 0, "unpaid_invoices_amount": "0.000000", "billing_currency": "USD" }, { "merchant_id": 6321, "open_charges_count": 0, "open_charges_amount": "0.000000", "draft_invoices_count": 2, "draft_invoices_amount": "257.750000", "unpaid_invoices_count": 1, "unpaid_invoices_amount": "99.990000", "billing_currency": "USD" } ] } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } } }, "/products": { "get": { "summary": "List products", "description": "Get a paginated list of products for the current merchant. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. Returns product details only — use the stock endpoints for quantities. Deleted products are excluded.", "operationId": "list-products", "tags": [ "Products" ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search language filter. Supported fields: `uuid` (uuid), `merchant_sku` (string), `title` (string). Substring matches require at least 3 characters. Clauses can be combined with `AND` / `OR`. Example: `title~\"widget\" AND merchant_sku:\"WIDGET-001\"`", "example": "title~\"widget\" AND merchant_sku:\"WIDGET-001\"" }, { "name": "sorts", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "type": "array", "maxItems": 2, "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "created_at", "updated_at", "merchant_sku", "title" ], "description": "The field to sort by" }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "The sort direction. Defaults to asc." }, "order": { "type": "integer", "minimum": 1, "description": "The position of this sort relative to the others" } }, "required": [ "field", "order" ] } }, "description": "Sort the results. Sorting by stock quantities is not supported here — products and stock are separate resources. Example: `sorts[0][field]=title&sorts[0][order]=1`" }, { "name": "expand", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "images", "identifiers", "tags" ] } }, "description": "Relations to include in each product. Omitted relations are absent from the response rather than null. Any other value is rejected with a 422. Example: `expand[]=identifiers&expand[]=tags`" }, { "name": "page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Page" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "The number of products per page", "minimum": 1, "maximum": 100, "default": 10, "example": 25 } } ], "responses": { "200": { "description": "A successful response returning the paginated list of products", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } }, "required": [ "data" ] } ] }, "examples": { "example": { "value": { "data": [ { "uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4", "created_at": "2026-04-01T09:34:55.000000Z", "updated_at": "2026-04-01T09:34:59.000000Z", "merchant_uuid": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e", "merchant_sku": "Synergist-163839", "title": "Synergistic Leather Shoes", "dimensions": { "length": 91, "width": 286, "height": 174, "unit": "mm" }, "weight": { "value": 1076, "unit": "g" }, "are_dimensions_locked": false, "is_deleted": false } ], "total": 37, "current_page": 1, "last_page": 4, "per_page": 10, "from": 1, "to": 10 } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } }, "post": { "summary": "Create a product", "description": "Create a product for the current merchant. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. `merchant_sku` must be unique among the merchant's products that have not been deleted, so a SKU freed up by deleting a product can be reused.", "operationId": "create-product", "tags": [ "Products" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant_sku": { "type": "string", "description": "The merchant's own Stock Keeping Unit identifier. Must be unique among the merchant's products.", "minLength": 2, "maxLength": 255, "example": "WIDGET-001" }, "title": { "type": "string", "description": "The title or name of the product", "minLength": 3, "maxLength": 255, "example": "Blue Widget" }, "dimensions": { "$ref": "#/components/schemas/DimensionsInput" }, "weight": { "$ref": "#/components/schemas/WeightInput" } }, "required": [ "merchant_sku", "title" ] } } } }, "responses": { "201": { "description": "A successful response returning the created product", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4", "created_at": "2026-04-01T09:34:55.000000Z", "updated_at": "2026-04-01T09:34:55.000000Z", "merchant_uuid": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e", "merchant_sku": "WIDGET-001", "title": "Blue Widget", "dimensions": { "length": 150, "width": 100, "height": 50, "unit": "mm" }, "weight": { "value": 500, "unit": "g" }, "are_dimensions_locked": false, "is_deleted": false, "images": [], "identifiers": [], "tags": [] } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/products/{product_uuid}": { "get": { "summary": "Get a product", "description": "Get a single product by its UUID, including its images, identifiers and tags. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. Returns product details only — use the stock endpoints for quantities. Deleted products are returned with `is_deleted` set to true.", "operationId": "get-product", "tags": [ "Products" ], "parameters": [ { "name": "product_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the product", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" } ], "responses": { "200": { "description": "A successful response returning the product", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4", "created_at": "2026-04-01T09:34:55.000000Z", "updated_at": "2026-04-01T09:34:59.000000Z", "merchant_uuid": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e", "merchant_sku": "Synergist-163839", "title": "Synergistic Leather Shoes", "dimensions": { "length": 91, "width": 286, "height": 174, "unit": "mm" }, "weight": { "value": 1076, "unit": "g" }, "are_dimensions_locked": false, "is_deleted": false, "images": [ { "id": 512, "product_uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4", "large_url": "https://example.com/images/512-large.jpg", "thumbnail_url": "https://example.com/images/512-thumb.jpg" } ], "identifiers": [ { "id": 1044, "product_uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4", "identifier": "B014IA92I8", "identifier_type": "ASIN", "created_at": "2026-04-01T09:34:55.000000Z", "updated_at": "2026-04-01T09:34:55.000000Z" } ], "tags": [] } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } }, "put": { "summary": "Update a product", "description": "Update a product's details. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. Only the properties present in the request body are changed; omitted properties are left as they are. A property sent as `null` is cleared. `dimensions` and `weight` are each written as a whole: their measurements and the unit must be sent together, and sending one as `null` clears it. When the product has `are_dimensions_locked` set, sending `dimensions` or `weight` returns a 422. Deleted products cannot be updated and return a 404.", "operationId": "update-product", "tags": [ "Products" ], "parameters": [ { "name": "product_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the product", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "The title or name of the product", "minLength": 3, "maxLength": 255, "example": "Blue Widget" }, "dimensions": { "$ref": "#/components/schemas/DimensionsInput" }, "weight": { "$ref": "#/components/schemas/WeightInput" } } } } } }, "responses": { "200": { "description": "A successful response returning the updated product", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4", "created_at": "2026-04-01T09:34:55.000000Z", "updated_at": "2026-04-01T09:34:59.000000Z", "merchant_uuid": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e", "merchant_sku": "Synergist-163839", "title": "Blue Widget", "dimensions": { "length": 150, "width": 100, "height": 50, "unit": "mm" }, "weight": { "value": 500, "unit": "g" }, "are_dimensions_locked": false, "is_deleted": false, "images": [], "identifiers": [], "tags": [] } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } }, "delete": { "summary": "Delete a product", "description": "Delete a product. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. The product is soft deleted: it disappears from the list endpoint, is still readable on the detail endpoint with `is_deleted` set to true, and frees its `merchant_sku` for reuse. Deleting a product that already has stock history requires the `products:delete_with_history` privilege and otherwise returns a 403. Deleting an already deleted product returns a 404.", "operationId": "delete-product", "tags": [ "Products" ], "parameters": [ { "name": "product_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the product", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" } ], "responses": { "204": { "description": "The product was successfully deleted" }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/suppliers": { "get": { "summary": "List suppliers", "description": "Get a paginated list of suppliers for the current merchant. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. Deleted suppliers are excluded.", "operationId": "index-suppliers", "tags": [ "Suppliers" ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search language filter. Supported fields: `name` (string), `uuid` (uuid). Substring matches require at least 3 characters. Clauses can be combined with `AND` / `OR`. Example: `name~\"acme\"`", "example": "name~\"acme\"" }, { "name": "sorts", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "type": "array", "maxItems": 2, "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "created_at", "name" ], "description": "The field to sort by" }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "The sort direction. Defaults to asc." }, "order": { "type": "integer", "minimum": 1, "description": "The position of this sort relative to the others" } }, "required": [ "field", "order" ] } }, "description": "Sort the results. Example: `sorts[0][field]=name&sorts[0][order]=1`" }, { "name": "page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Page" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "The number of suppliers per page", "minimum": 1, "maximum": 100, "default": 10, "example": 25 } } ], "responses": { "200": { "description": "A successful response returning the paginated list of suppliers", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Supplier" } } }, "required": [ "data" ] } ] }, "examples": { "example": { "value": { "data": [ { "uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4", "merchant_uuid": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e", "name": "Acme Wholesale", "default_currency": "USD", "created_at": "2026-04-01T09:34:55.000000Z", "updated_at": "2026-04-01T09:34:59.000000Z", "is_deleted": false } ], "total": 1, "current_page": 1, "last_page": 1, "per_page": 10, "from": 1, "to": 1 } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } }, "post": { "summary": "Create a supplier", "description": "Create a supplier for the current merchant. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422.", "operationId": "create-supplier", "tags": [ "Suppliers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the supplier", "maxLength": 255, "example": "Acme Wholesale" }, "default_currency": { "type": "string", "description": "The ISO 4217 currency code used to pre-fill new cost tiers for this supplier's items", "pattern": "^[A-Z]{3}$", "example": "USD" } }, "required": [ "name", "default_currency" ] } } } }, "responses": { "201": { "description": "A successful response returning the created supplier", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Supplier" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4", "merchant_uuid": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e", "name": "Acme Wholesale", "default_currency": "USD", "created_at": "2026-04-01T09:34:55.000000Z", "updated_at": "2026-04-01T09:34:55.000000Z", "is_deleted": false } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/suppliers/{supplier_uuid}": { "get": { "summary": "Get a supplier", "description": "Get a single supplier by its UUID. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. Deleted suppliers are returned with `is_deleted` set to true.", "operationId": "show-supplier", "tags": [ "Suppliers" ], "parameters": [ { "name": "supplier_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the supplier", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" } ], "responses": { "200": { "description": "A successful response returning the supplier", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Supplier" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4", "merchant_uuid": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e", "name": "Acme Wholesale", "default_currency": "USD", "created_at": "2026-04-01T09:34:55.000000Z", "updated_at": "2026-04-01T09:34:59.000000Z", "is_deleted": false } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } }, "put": { "summary": "Update a supplier", "description": "Update a supplier's details. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. Only the properties present in the request body are changed; omitted properties are left as they are. Deleted suppliers cannot be updated and return a 404.", "operationId": "update-supplier", "tags": [ "Suppliers" ], "parameters": [ { "name": "supplier_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the supplier", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the supplier", "maxLength": 255, "example": "Acme Wholesale" }, "default_currency": { "type": "string", "description": "The ISO 4217 currency code used to pre-fill new cost tiers for this supplier's items", "pattern": "^[A-Z]{3}$", "example": "USD" } } } } } }, "responses": { "200": { "description": "A successful response returning the updated supplier", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Supplier" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4", "merchant_uuid": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e", "name": "Acme Wholesale", "default_currency": "USD", "created_at": "2026-04-01T09:34:55.000000Z", "updated_at": "2026-04-01T09:34:59.000000Z", "is_deleted": false } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } }, "delete": { "summary": "Delete a supplier", "description": "Delete a supplier. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. The supplier is soft deleted: it disappears from the list endpoint and is still readable on the detail endpoint with `is_deleted` set to true. Deleting an already deleted supplier returns a 404.", "operationId": "delete-supplier", "tags": [ "Suppliers" ], "parameters": [ { "name": "supplier_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the supplier", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" } ], "responses": { "204": { "description": "The supplier was successfully deleted" }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/suppliers/{supplier_uuid}/items": { "get": { "summary": "List supplier items", "description": "Get a paginated list of items for a supplier. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. A supplier outside the narrated account returns a 404. Deleted items are excluded.", "operationId": "index-supplier-items", "tags": [ "Suppliers" ], "parameters": [ { "name": "supplier_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the supplier", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search language filter. Supported fields: `sku` (string), `description` (string). Substring matches require at least 3 characters. Clauses can be combined with `AND` / `OR`. Example: `sku~\"widget\"`", "example": "sku~\"widget\"" }, { "name": "product_uuid", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter items linked to this product", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" }, { "name": "sorts", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "type": "array", "maxItems": 2, "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "created_at", "sku" ], "description": "The field to sort by" }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "The sort direction. Defaults to asc." }, "order": { "type": "integer", "minimum": 1, "description": "The position of this sort relative to the others" } }, "required": [ "field", "order" ] } }, "description": "Sort the results. Example: `sorts[0][field]=sku&sorts[0][order]=1`" }, { "name": "page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Page" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "The number of items per page", "minimum": 1, "maximum": 100, "default": 10, "example": 25 } } ], "responses": { "200": { "description": "A successful response returning the paginated list of supplier items", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierItem" } } }, "required": [ "data" ] } ] }, "examples": { "example": { "value": { "data": [ { "uuid": "2b6f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d5", "supplier_uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4", "merchant_uuid": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e", "sku": "ACME-WIDGET-001", "description": "Blue widget, bulk pack of 10", "product_uuid": null, "costs": [ { "minimum_order_quantity": 100, "current_cost": { "uuid": "3c7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d6", "amount": "12.3700", "currency": "USD", "effective_at": "2026-04-01T09:34:55.000000Z" }, "upcoming_cost": null } ], "identifiers": [ { "type": "UPC", "value": "123456789012" } ], "created_at": "2026-04-01T09:34:55.000000Z", "updated_at": "2026-04-01T09:34:59.000000Z", "is_deleted": false } ], "total": 1, "current_page": 1, "last_page": 1, "per_page": 10, "from": 1, "to": 1 } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } }, "post": { "summary": "Create a supplier item", "description": "Create a catalogue item for a supplier. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. A supplier outside the narrated account returns a 404. `sku` must be unique among the supplier's items that have not been deleted. `product_uuid`, when present, must reference a non-deleted product owned by the same merchant.", "operationId": "create-supplier-item", "tags": [ "Suppliers" ], "parameters": [ { "name": "supplier_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the supplier", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sku": { "type": "string", "description": "The supplier's own identifier for this item. Unique among the supplier's items that have not been deleted.", "maxLength": 255, "example": "ACME-WIDGET-001" }, "description": { "type": [ "string", "null" ], "description": "A description of the item", "example": "Blue widget, bulk pack of 10" }, "product_uuid": { "type": [ "string", "null" ], "format": "uuid", "description": "The UUID of the product this supplier item is linked to. Must be a non-deleted product owned by the same merchant.", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" }, "costs": { "type": "array", "description": "Quantity-break cost tiers for this item. Minimum order quantities must be unique within the payload.", "items": { "type": "object", "properties": { "minimum_order_quantity": { "type": "integer", "minimum": 1, "example": 100 }, "cost": { "type": "object", "properties": { "amount": { "type": "number", "minimum": 0, "example": 12.37 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "USD" } }, "additionalProperties": false, "required": [ "amount", "currency" ] } }, "additionalProperties": false, "required": [ "minimum_order_quantity", "cost" ] } }, "identifiers": { "type": "array", "description": "Typed barcode identifiers for this item. The combination of type and value must be unique within the payload.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "UPC", "EAN", "GTIN", "ISBN" ], "example": "UPC" }, "value": { "type": "string", "example": "123456789012" } }, "additionalProperties": false, "required": [ "type", "value" ] } } }, "required": [ "sku" ] } } } }, "responses": { "201": { "description": "A successful response returning the created supplier item", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SupplierItem" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "2b6f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d5", "supplier_uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4", "merchant_uuid": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e", "sku": "ACME-WIDGET-001", "description": "Blue widget, bulk pack of 10", "product_uuid": null, "costs": [ { "minimum_order_quantity": 100, "current_cost": { "uuid": "3c7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d6", "amount": "12.3700", "currency": "USD", "effective_at": "2026-04-01T09:34:55.000000Z" }, "upcoming_cost": null } ], "identifiers": [ { "type": "UPC", "value": "123456789012" } ], "created_at": "2026-04-01T09:34:55.000000Z", "updated_at": "2026-04-01T09:34:55.000000Z", "is_deleted": false } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/suppliers/{supplier_uuid}/items/{supplier_item_uuid}": { "get": { "summary": "Get a supplier item", "description": "Get a single supplier item by its UUID, including its cost tiers and identifiers. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. A supplier or item outside the narrated account returns a 404. Deleted items are returned with `is_deleted` set to true.", "operationId": "show-supplier-item", "tags": [ "Suppliers" ], "parameters": [ { "name": "supplier_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the supplier", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" }, { "name": "supplier_item_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the supplier item", "example": "2b6f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d5" } ], "responses": { "200": { "description": "A successful response returning the supplier item", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SupplierItem" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "2b6f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d5", "supplier_uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4", "merchant_uuid": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e", "sku": "ACME-WIDGET-001", "description": "Blue widget, bulk pack of 10", "product_uuid": null, "costs": [ { "minimum_order_quantity": 100, "current_cost": { "uuid": "3c7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d6", "amount": "12.3700", "currency": "USD", "effective_at": "2026-04-01T09:34:55.000000Z" }, "upcoming_cost": null } ], "identifiers": [ { "type": "UPC", "value": "123456789012" } ], "created_at": "2026-04-01T09:34:55.000000Z", "updated_at": "2026-04-01T09:34:59.000000Z", "is_deleted": false } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } }, "put": { "summary": "Update a supplier item", "description": "Update a supplier item's own attributes (`sku`, `description`, `product_uuid`). Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. A supplier or item outside the narrated account returns a 404. Only the properties present in the request body are changed; omitted properties are left as they are. Cost tiers and identifiers are managed separately: costs are append-only via `POST .../costs` and `DELETE .../costs/{supplier_item_cost_uuid}`, and identifiers are set-replaced via `PUT .../identifiers`.", "operationId": "update-supplier-item", "tags": [ "Suppliers" ], "parameters": [ { "name": "supplier_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the supplier", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" }, { "name": "supplier_item_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the supplier item", "example": "2b6f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d5" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sku": { "type": "string", "description": "The supplier's own identifier for this item. Unique among the supplier's items that have not been deleted.", "maxLength": 255, "example": "ACME-WIDGET-001" }, "description": { "type": [ "string", "null" ], "description": "A description of the item", "example": "Blue widget, bulk pack of 10" }, "product_uuid": { "type": [ "string", "null" ], "format": "uuid", "description": "The UUID of the product this supplier item is linked to. Must be a non-deleted product owned by the same merchant.", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" } } } } } }, "responses": { "200": { "description": "A successful response returning the updated supplier item", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SupplierItem" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "2b6f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d5", "supplier_uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4", "merchant_uuid": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e", "sku": "ACME-WIDGET-001", "description": "Blue widget, bulk pack of 10", "product_uuid": null, "costs": [ { "minimum_order_quantity": 100, "current_cost": { "uuid": "3c7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d6", "amount": "12.3700", "currency": "USD", "effective_at": "2026-04-01T09:34:55.000000Z" }, "upcoming_cost": null } ], "identifiers": [ { "type": "UPC", "value": "123456789012" } ], "created_at": "2026-04-01T09:34:55.000000Z", "updated_at": "2026-04-01T09:34:59.000000Z", "is_deleted": false } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } }, "delete": { "summary": "Delete a supplier item", "description": "Delete a supplier item. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. A supplier or item outside the narrated account returns a 404. The item is soft deleted: it disappears from the list endpoint and is still readable on the detail endpoint with `is_deleted` set to true, and frees its `sku` for reuse. Deleting an already deleted item returns a 404.", "operationId": "delete-supplier-item", "tags": [ "Suppliers" ], "parameters": [ { "name": "supplier_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the supplier", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" }, { "name": "supplier_item_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the supplier item", "example": "2b6f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d5" } ], "responses": { "204": { "description": "The supplier item was successfully deleted" }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/suppliers/{supplier_uuid}/items/{supplier_item_uuid}/costs": { "post": { "summary": "Create a supplier item cost row", "description": "Appends a new price for a minimum order quantity. Costs are append-only: this always inserts a new row rather than editing an existing one, so this can be used both to add a brand-new tier and to record a price change for a tier that already exists — the tier's `current_cost` is simply whichever non-future row for that minimum order quantity has the latest `effective_at`. Set `effective_at` to a future date to schedule a price change in advance; it surfaces as `upcoming_cost` until that date arrives. Omit it (or send null) to take effect immediately. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. A supplier or item outside the narrated account returns a 404.", "operationId": "create-supplier-item-cost", "tags": [ "Suppliers" ], "parameters": [ { "name": "supplier_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the supplier", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" }, { "name": "supplier_item_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the supplier item", "example": "2b6f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d5" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "minimum_order_quantity": { "type": "integer", "minimum": 1, "example": 100 }, "cost": { "type": "object", "properties": { "amount": { "type": "number", "minimum": 0, "example": 12.37 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "USD" } }, "additionalProperties": false, "required": [ "amount", "currency" ] }, "effective_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime from which this price takes effect. Defaults to now when omitted or null; a future value schedules the price and surfaces it as `upcoming_cost` until it arrives.", "example": "2026-04-01T09:34:55.000000Z" } }, "required": [ "minimum_order_quantity", "cost" ] } } } }, "responses": { "201": { "description": "A successful response returning the created cost row", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "SupplierItemCostRow", "type": "object", "description": "A single, individually addressable cost row for a supplier item. Costs are append-only: each price for a minimum order quantity is its own row, created via `POST .../costs` and soft deleted via `DELETE .../costs/{supplier_item_cost_uuid}` rather than edited in place.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "The UUID of this cost row", "example": "3c7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d6" }, "minimum_order_quantity": { "type": "integer", "description": "The minimum order quantity this cost applies to", "minimum": 1, "example": 100 }, "cost": { "type": "object", "properties": { "amount": { "type": "string", "description": "The cost amount, expressed as a decimal string with 4 decimal places", "example": "12.3700" }, "currency": { "type": "string", "description": "The ISO 4217 currency code this cost is denominated in", "example": "USD" } }, "additionalProperties": false, "required": [ "amount", "currency" ] }, "effective_at": { "type": "string", "format": "date-time", "description": "The ISO 8601 datetime from which this cost is, or will be, in effect", "example": "2026-04-01T09:34:55.000000Z" } }, "additionalProperties": false, "required": [ "uuid", "minimum_order_quantity", "cost", "effective_at" ] } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "3c7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d6", "minimum_order_quantity": 100, "cost": { "amount": "12.3700", "currency": "USD" }, "effective_at": "2026-04-01T09:34:55.000000Z" } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/suppliers/{supplier_uuid}/items/{supplier_item_uuid}/costs/{supplier_item_cost_uuid}": { "delete": { "summary": "Delete a supplier item cost row", "description": "Soft deletes a single cost row by its own UUID, preserving its price history. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. A supplier, item, or cost row outside the narrated account returns a 404. Deleting the row currently in effect for a minimum order quantity does not retire the tier: the next most recent non-future row for that quantity, if any, becomes current again.", "operationId": "delete-supplier-item-cost", "tags": [ "Suppliers" ], "parameters": [ { "name": "supplier_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the supplier", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" }, { "name": "supplier_item_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the supplier item", "example": "2b6f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d5" }, { "name": "supplier_item_cost_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the cost row", "example": "3c7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d6" } ], "responses": { "204": { "description": "The cost row was successfully deleted" }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/suppliers/{supplier_uuid}/items/{supplier_item_uuid}/identifiers": { "put": { "summary": "Replace a supplier item's identifiers", "description": "Replaces every existing identifier for this item with exactly the identifiers present in the payload. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. A supplier or item outside the narrated account returns a 404. The combination of type and value must be unique within the payload. Send an empty array to remove every existing identifier.", "operationId": "update-supplier-item-identifiers", "tags": [ "Suppliers" ], "parameters": [ { "name": "supplier_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the supplier", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" }, { "name": "supplier_item_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the supplier item", "example": "2b6f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d5" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identifiers": { "type": "array", "description": "The complete set of identifiers for this item. Must always be present, even as an empty array, to clear every identifier.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "UPC", "EAN", "GTIN", "ISBN" ], "example": "UPC" }, "value": { "type": "string", "example": "123456789012" } }, "additionalProperties": false, "required": [ "type", "value" ] } } }, "required": [ "identifiers" ] } } } }, "responses": { "200": { "description": "A successful response returning the updated supplier item", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SupplierItem" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "2b6f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d5", "supplier_uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4", "merchant_uuid": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e", "sku": "ACME-WIDGET-001", "description": "Blue widget, bulk pack of 10", "product_uuid": null, "costs": [], "identifiers": [ { "type": "UPC", "value": "123456789012" } ], "created_at": "2026-04-01T09:34:55.000000Z", "updated_at": "2026-04-01T09:34:59.000000Z", "is_deleted": false } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/sourcing/amazon/matches": { "get": { "summary": "List Amazon catalog item matches", "description": "Get a paginated list of the merchant's matches between supplier items and Amazon catalog items, newest first. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. Requires the `suppliers:view` permission. Matches whose supplier item or supplier is deleted are excluded. Filters combine with AND; an invalid filter returns a 422.", "operationId": "index-amazon-catalog-item-matches", "tags": [ "Sourcing" ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "accepted", "rejected" ] }, "description": "Only matches with this status, as derived from `accepted_at` and `rejected_at`. Omit for every status.", "example": "pending" }, { "name": "supplier_uuid", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Only matches for items of this supplier", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" }, { "name": "supplier_item_uuid", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Only matches for this supplier item", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" }, { "name": "page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Page" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "The number of matches per page", "minimum": 1, "maximum": 100, "default": 10, "example": 25 } } ], "responses": { "200": { "description": "A successful response returning the paginated list of matches", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AmazonCatalogItemMatch" } } }, "required": [ "data" ] } ] }, "examples": { "example": { "value": { "data": [ { "uuid": "019b3c4d-5e6f-80ef-9a0b-1c2d3e4f5a6b", "merchant_uuid": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e", "method": "shared_identifier", "matched_identifier_type": "EAN", "matched_identifier_value": "0012345678905", "status": "accepted", "accepted_at": "2026-04-01T09:34:55.000000Z", "rejected_at": null, "decided_by_user_uuid": "5d2e1f0a-b5a9-4d1a-a2d5-d0e0c2b1c3d7", "volume": null, "cost_override": null, "fees": [], "supplier": { "uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4", "name": "Acme Wholesale" }, "supplier_item": { "uuid": "2b6f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d5", "sku": "ACME-WIDGET-001", "description": "Blue widget, bulk pack of 10" }, "amazon_catalog_item": { "uuid": "3c7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d6", "asin": "B000123456", "title": "Acme Blue Widget, Pack of 10", "marketplace_id": "ATVPDKIKX0DER" }, "created_at": "2026-04-01T09:30:00.000000Z", "updated_at": "2026-04-01T09:34:55.000000Z" } ], "total": 1, "current_page": 1, "last_page": 1, "per_page": 10, "from": 1, "to": 1 } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/sourcing/amazon/compositions": { "get": { "summary": "List Amazon sourcing compositions", "description": "Lists complete live compositions for the selected merchant, newest first. An optional supplier item filter selects compositions containing that item without truncating their components.", "operationId": "index-amazon-sourcing-compositions", "tags": [ "Sourcing" ], "parameters": [ { "name": "supplier_item_uuid", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Page" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } } ], "responses": { "200": { "description": "Paginated compositions", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AmazonSourcingComposition" } } }, "required": [ "data" ] } ] } } } }, "400": { "description": "The narrated service provider is not connected to the merchant", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant": { "type": "string" } }, "required": [ "merchant" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } }, "post": { "summary": "Create an immutable Amazon sourcing composition", "description": "Creates one composition and all components atomically. Every component count and conversion is required; duplicate supplier items and revision, position, or decision fields are rejected.", "operationId": "create-amazon-sourcing-composition", "tags": [ "Sourcing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amazon_catalog_item_uuid": { "type": "string", "format": "uuid" }, "components": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "supplier_item_uuid": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "units_per_supplier_unit": { "type": "integer", "minimum": 1, "maximum": 2147483647 } }, "required": [ "supplier_item_uuid", "quantity", "units_per_supplier_unit" ], "additionalProperties": false } } }, "required": [ "amazon_catalog_item_uuid", "components" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Composition created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AmazonSourcingComposition" } }, "required": [ "data" ] } } } }, "400": { "description": "The narrated service provider is not connected to the merchant", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant": { "type": "string" } }, "required": [ "merchant" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/sourcing/amazon/compositions/{amazon_sourcing_composition_uuid}": { "parameters": [ { "name": "amazon_sourcing_composition_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Show an Amazon sourcing composition", "operationId": "show-amazon-sourcing-composition", "tags": [ "Sourcing" ], "responses": { "200": { "description": "Complete composition", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AmazonSourcingComposition" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } }, "delete": { "summary": "Delete an Amazon sourcing composition", "description": "Deletes the owned composition, its components and its verification, including when a supplier parent has since been soft-deleted.", "operationId": "delete-amazon-sourcing-composition", "tags": [ "Sourcing" ], "responses": { "204": { "description": "Composition deleted" }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/sourcing/amazon/compositions/{amazon_sourcing_composition_uuid}/accept": { "parameters": [ { "name": "amazon_sourcing_composition_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "summary": "Accept an Amazon sourcing composition", "description": "Accepts the composition: sets `verification.accepted_at` to now and `verification.decided_by_user_uuid` to the signed-in user, and clears `verification.rejected_at`. Accepting an already accepted composition changes nothing and keeps the original timestamp and decider. Requires a merchant scope; a service provider scope is optional and must be connected to the merchant, otherwise the request returns a 400. A request without a merchant scope returns a 422. A composition outside the narrated merchant, or with a deleted supplier item or supplier, returns a 404 before permissions are checked. Requires the `suppliers:manage` permission and a signed-in user. The request body is ignored: the decider is the signed-in user and the timestamp is the current time. The decision concerns the identity of the exact immutable target, components, quantities and conversions; it does not approve economics, change legacy matches or trigger calculations.", "operationId": "accept-amazon-sourcing-composition", "tags": [ "Sourcing" ], "responses": { "200": { "description": "The composition, now accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AmazonSourcingComposition" } }, "required": [ "data" ] } } } }, "400": { "description": "The narrated service provider is not connected to the merchant", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant": { "type": "string" } }, "required": [ "merchant" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/sourcing/amazon/compositions/{amazon_sourcing_composition_uuid}/reject": { "parameters": [ { "name": "amazon_sourcing_composition_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "summary": "Reject an Amazon sourcing composition", "description": "Rejects the composition: sets `verification.rejected_at` to now and `verification.decided_by_user_uuid` to the signed-in user, and clears `verification.accepted_at`. Rejecting an already rejected composition changes nothing and keeps the original timestamp and decider. Requires a merchant scope; a service provider scope is optional and must be connected to the merchant, otherwise the request returns a 400. A request without a merchant scope returns a 422. A composition outside the narrated merchant, or with a deleted supplier item or supplier, returns a 404 before permissions are checked. Requires the `suppliers:manage` permission and a signed-in user. The request body is ignored: the decider is the signed-in user and the timestamp is the current time. The decision concerns the identity of the exact immutable target, components, quantities and conversions; it does not approve economics, change legacy matches or trigger calculations.", "operationId": "reject-amazon-sourcing-composition", "tags": [ "Sourcing" ], "responses": { "200": { "description": "The composition, now rejected", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AmazonSourcingComposition" } }, "required": [ "data" ] } } } }, "400": { "description": "The narrated service provider is not connected to the merchant", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant": { "type": "string" } }, "required": [ "merchant" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/sourcing/amazon/compositions/{amazon_sourcing_composition_uuid}/reopen": { "parameters": [ { "name": "amazon_sourcing_composition_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "summary": "Reopen an Amazon sourcing composition", "description": "Returns the composition to pending: clears `verification.accepted_at`, `verification.rejected_at` and `verification.decided_by_user_uuid`. Reopening a pending composition changes nothing. Requires a merchant scope; a service provider scope is optional and must be connected to the merchant, otherwise the request returns a 400. A request without a merchant scope returns a 422. A composition outside the narrated merchant, or with a deleted supplier item or supplier, returns a 404 before permissions are checked. Requires the `suppliers:manage` permission and a signed-in user. The request body is ignored. The decision concerns the identity of the exact immutable target, components, quantities and conversions; it does not approve economics, change legacy matches or trigger calculations.", "operationId": "reopen-amazon-sourcing-composition", "tags": [ "Sourcing" ], "responses": { "200": { "description": "The composition, now pending", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AmazonSourcingComposition" } }, "required": [ "data" ] } } } }, "400": { "description": "The narrated service provider is not connected to the merchant", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant": { "type": "string" } }, "required": [ "merchant" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/sourcing/amazon/matches/discover": { "post": { "summary": "Request Amazon catalog match discovery", "description": "Queue discovery of new Amazon catalog item matches across all of the narrated merchant's supplier items. Discovery runs asynchronously: the 202 response means the request was queued, not that any matches exist yet; poll the list endpoint for results. Discovery only adds pending matches for new pairs and never changes or reopens an existing match. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. Requires the `suppliers:manage` permission. The request takes no body.", "operationId": "request-amazon-catalog-match-discovery", "tags": [ "Sourcing" ], "responses": { "202": { "description": "Discovery was queued for the merchant", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "merchant_uuid": { "type": "string", "format": "uuid", "description": "The merchant discovery was queued for" }, "status": { "type": "string", "enum": [ "queued" ], "description": "Always `queued`" } }, "additionalProperties": false, "required": [ "merchant_uuid", "status" ] } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "merchant_uuid": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e", "status": "queued" } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/sourcing/amazon/matches/{amazon_catalog_item_match_uuid}/accept": { "post": { "summary": "Accept an Amazon catalog item match", "description": "Accept the match: sets `accepted_at` to now and `decided_by_user_uuid` to the authenticated user, and clears `rejected_at`, in one update. A rejected match can be accepted. Accepting an already accepted match changes nothing and keeps the original `accepted_at` and decider. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. Requires the `suppliers:manage` permission and a signed-in user. A match outside the narrated merchant, or whose supplier item or supplier is deleted, returns a 404. The request takes no body.", "operationId": "accept-amazon-catalog-item-match", "tags": [ "Sourcing" ], "parameters": [ { "name": "amazon_catalog_item_match_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the match", "example": "019b3c4d-5e6f-80ef-9a0b-1c2d3e4f5a6b" } ], "responses": { "200": { "description": "The match, now accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AmazonCatalogItemMatch" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "019b3c4d-5e6f-80ef-9a0b-1c2d3e4f5a6b", "merchant_uuid": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e", "method": "shared_identifier", "matched_identifier_type": "EAN", "matched_identifier_value": "0012345678905", "status": "accepted", "accepted_at": "2026-04-01T09:34:55.000000Z", "rejected_at": null, "decided_by_user_uuid": "5d2e1f0a-b5a9-4d1a-a2d5-d0e0c2b1c3d7", "volume": null, "cost_override": null, "fees": [], "supplier": { "uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4", "name": "Acme Wholesale" }, "supplier_item": { "uuid": "2b6f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d5", "sku": "ACME-WIDGET-001", "description": "Blue widget, bulk pack of 10" }, "amazon_catalog_item": { "uuid": "3c7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d6", "asin": "B000123456", "title": "Acme Blue Widget, Pack of 10", "marketplace_id": "ATVPDKIKX0DER" }, "created_at": "2026-04-01T09:30:00.000000Z", "updated_at": "2026-04-01T09:34:55.000000Z" } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/sourcing/amazon/matches/{amazon_catalog_item_match_uuid}/reject": { "post": { "summary": "Reject an Amazon catalog item match", "description": "Reject the match: sets `rejected_at` to now and `decided_by_user_uuid` to the authenticated user, and clears `accepted_at`, in one update. An accepted match can be rejected. Rejecting an already rejected match changes nothing and keeps the original `rejected_at` and decider. Discovery never reopens a rejected match. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. Requires the `suppliers:manage` permission and a signed-in user. A match outside the narrated merchant, or whose supplier item or supplier is deleted, returns a 404. The request takes no body.", "operationId": "reject-amazon-catalog-item-match", "tags": [ "Sourcing" ], "parameters": [ { "name": "amazon_catalog_item_match_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the match", "example": "019b3c4d-5e6f-80ef-9a0b-1c2d3e4f5a6b" } ], "responses": { "200": { "description": "The match, now rejected", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AmazonCatalogItemMatch" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "019b3c4d-5e6f-80ef-9a0b-1c2d3e4f5a6b", "merchant_uuid": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e", "method": "shared_identifier", "matched_identifier_type": "EAN", "matched_identifier_value": "0012345678905", "status": "rejected", "accepted_at": null, "rejected_at": "2026-04-01T09:34:55.000000Z", "decided_by_user_uuid": "5d2e1f0a-b5a9-4d1a-a2d5-d0e0c2b1c3d7", "volume": null, "cost_override": null, "fees": [], "supplier": { "uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4", "name": "Acme Wholesale" }, "supplier_item": { "uuid": "2b6f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d5", "sku": "ACME-WIDGET-001", "description": "Blue widget, bulk pack of 10" }, "amazon_catalog_item": { "uuid": "3c7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d6", "asin": "B000123456", "title": "Acme Blue Widget, Pack of 10", "marketplace_id": "ATVPDKIKX0DER" }, "created_at": "2026-04-01T09:30:00.000000Z", "updated_at": "2026-04-01T09:34:55.000000Z" } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/sourcing/amazon/matches/{amazon_catalog_item_match_uuid}/reopen": { "post": { "summary": "Reopen an Amazon catalog item match", "description": "Return the match to pending by clearing `accepted_at`, `rejected_at` and `decided_by_user_uuid`. Reopening a pending match changes nothing. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. Requires the `suppliers:manage` permission and a signed-in user. A match outside the narrated merchant, or whose supplier item or supplier is deleted, returns a 404. The request takes no body.", "operationId": "reopen-amazon-catalog-item-match", "tags": [ "Sourcing" ], "parameters": [ { "name": "amazon_catalog_item_match_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the match", "example": "019b3c4d-5e6f-80ef-9a0b-1c2d3e4f5a6b" } ], "responses": { "200": { "description": "The match, now pending", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AmazonCatalogItemMatch" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "uuid": "019b3c4d-5e6f-80ef-9a0b-1c2d3e4f5a6b", "merchant_uuid": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e", "method": "shared_identifier", "matched_identifier_type": "EAN", "matched_identifier_value": "0012345678905", "status": "pending", "accepted_at": null, "rejected_at": null, "decided_by_user_uuid": null, "volume": null, "cost_override": null, "fees": [], "supplier": { "uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4", "name": "Acme Wholesale" }, "supplier_item": { "uuid": "2b6f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d5", "sku": "ACME-WIDGET-001", "description": "Blue widget, bulk pack of 10" }, "amazon_catalog_item": { "uuid": "3c7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d6", "asin": "B000123456", "title": "Acme Blue Widget, Pack of 10", "marketplace_id": "ATVPDKIKX0DER" }, "created_at": "2026-04-01T09:30:00.000000Z", "updated_at": "2026-04-01T09:34:55.000000Z" } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/sourcing/amazon/matches/{amazon_catalog_item_match_uuid}/assumptions": { "patch": { "summary": "Update Amazon match assumptions", "description": "Requires suppliers:manage in merchant scope. A narrated provider must be connected to the merchant. Partially updates merchant assumptions; omitted fields are preserved, while null volume or cost clears that assumption. Cost amounts are nonnegative decimal strings from 0 through 99999999.9999 after half-up rounding to four decimal places, and currencies are supported uppercase ISO codes. An empty patch is a no-op. A successful change queues recalculation after commit, so the returned inputs are current but opportunity results may remain stale until the job runs.", "operationId": "update-amazon-match-assumptions", "tags": [ "Sourcing" ], "parameters": [ { "name": "amazon_catalog_item_match_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "volume": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2147483647 }, "cost": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amount", "currency" ], "additionalProperties": false } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "Saved assumptions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AmazonCatalogItemMatch" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "The narrated service provider is not connected to the merchant", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant": { "type": "string" } }, "required": [ "merchant" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/sourcing/amazon/matches/{amazon_catalog_item_match_uuid}/fees": { "put": { "summary": "Replace Amazon match fees", "description": "Requires suppliers:manage in merchant scope. A narrated provider must be connected to the merchant. Atomically replaces up to 100 merchant-entered per-unit fees. Amounts are nonnegative decimal strings from 0 through 99999999.9999 after half-up rounding to four decimal places, and currencies are supported uppercase ISO codes. An empty array clears the set; omitting fees is invalid. Identical normalized input is a no-op. Mixed currencies are retained as inputs but cause currency_mismatch during calculation. A successful change queues recalculation after commit.", "operationId": "replace-amazon-match-fees", "tags": [ "Sourcing" ], "parameters": [ { "name": "amazon_catalog_item_match_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fees": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shipping", "prep", "other" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "amount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "kind", "label", "amount", "currency" ], "additionalProperties": false } } }, "required": [ "fees" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Persisted normalized fee set", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AmazonCatalogItemMatch" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "The narrated service provider is not connected to the merchant", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant": { "type": "string" } }, "required": [ "merchant" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/sourcing/amazon/opportunities": { "get": { "summary": "List Amazon opportunities", "description": "Returns only stored opportunities whose merchant match is currently pending or accepted and whose supplier item and supplier are live. Requires merchant scope and `suppliers:view`; an optional narrated provider must be connected. Filters combine with AND. The summary covers the entire filtered eligible set, independently of the page. Currency totals never perform FX and sum only non-null estimated profit from non-skipped rows; contributor count identifies partial totals, and a zero count has a null total. Dates use ISO 8601; period_end is exclusive. Fees are not yet estimated (`fees_estimated` is false), and empty known_fees does not assert zero Amazon fees.", "operationId": "index-amazon-opportunities", "tags": [ "Sourcing" ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "accepted" ] } }, { "name": "supplier_uuid", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "supplier_item_uuid", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "$ref": "#/components/schemas/Page" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } } ], "responses": { "200": { "description": "Paginated opportunities and whole-filter summary", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "AmazonOpportunity", "type": "object", "description": "A stored Amazon profitability calculation for a currently eligible supplier-item match.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "match": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "merchant_uuid": { "type": "string", "format": "uuid" }, "method": { "type": "string" }, "matched_identifier_type": { "type": "string" }, "matched_identifier_value": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted" ] }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "rejected_at": { "type": [ "string", "null" ], "format": "date-time" }, "decided_by_user_uuid": { "type": [ "string", "null" ], "format": "uuid" } }, "additionalProperties": false, "required": [ "uuid", "merchant_uuid", "method", "matched_identifier_type", "matched_identifier_value", "status", "accepted_at", "rejected_at", "decided_by_user_uuid" ] }, "kind": { "type": "string" }, "model": { "type": "string", "description": "The dated calculation model identifier." }, "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date", "description": "Exclusive end of the calculation period." }, "calculated_at": { "type": "string", "format": "date-time" }, "currency": { "type": [ "string", "null" ] }, "sell_price": { "$ref": "#/components/schemas/NullableMoney" }, "supplier_cost": { "$ref": "#/components/schemas/NullableMoney" }, "merchant_fees_total": { "$ref": "#/components/schemas/NullableMoney" }, "profit_per_unit": { "$ref": "#/components/schemas/NullableMoney" }, "estimated_profit": { "$ref": "#/components/schemas/NullableMoney" }, "volume": { "type": [ "integer", "null" ], "minimum": 1 }, "selected_supplier_item_cost_uuid": { "type": [ "string", "null" ], "format": "uuid" }, "known_fees": { "type": "array", "description": "Known fees used by this calculation. An empty array does not mean Amazon fees are zero.", "items": { "type": "object" } }, "skipped_reason": { "type": [ "string", "null" ], "enum": [ "no_price_history", "no_current_cost", "currency_mismatch", "fee_estimate_unavailable", null ] }, "inputs": { "type": "object", "properties": { "fees_estimated": { "type": "boolean", "enum": [ false ] }, "price_currencies": { "type": "array", "items": { "type": "string" } }, "supplier_cost": { "type": [ "object", "null" ] }, "merchant_fees": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "kind", "label", "amount", "currency" ], "additionalProperties": false } }, "volume": { "type": [ "integer", "null" ], "minimum": 1 } }, "required": [ "fees_estimated", "price_currencies", "supplier_cost" ] }, "supplier": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "additionalProperties": false, "required": [ "uuid", "name" ] }, "supplier_item": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "description": { "type": [ "string", "null" ] } }, "additionalProperties": false, "required": [ "uuid", "sku", "description" ] }, "amazon_catalog_item": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "asin": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "marketplace_id": { "type": "string" } }, "additionalProperties": false, "required": [ "uuid", "asin", "title", "marketplace_id" ] } }, "additionalProperties": false, "required": [ "uuid", "match", "kind", "model", "period_start", "period_end", "calculated_at", "currency", "sell_price", "supplier_cost", "merchant_fees_total", "profit_per_unit", "estimated_profit", "volume", "selected_supplier_item_cost_uuid", "known_fees", "skipped_reason", "inputs", "supplier", "supplier_item", "amazon_catalog_item" ] } }, "summary": { "type": "object", "properties": { "total_count": { "type": "integer" }, "calculated_count": { "type": "integer" }, "skipped_count": { "type": "integer" }, "currencies": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "estimated_profit": { "$ref": "#/components/schemas/NullableMoney" }, "contributing_opportunity_count": { "type": "integer" } }, "additionalProperties": false, "required": [ "currency", "estimated_profit", "contributing_opportunity_count" ] } } }, "additionalProperties": false, "required": [ "total_count", "calculated_count", "skipped_count", "currencies" ] } }, "required": [ "data", "summary" ] } ] } } } }, "400": { "description": "The narrated service provider is not connected to the merchant", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant": { "type": "string" } }, "required": [ "merchant" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/sourcing/amazon/opportunities/recalculate": { "post": { "summary": "Request Amazon opportunity recalculation", "description": "Queues asynchronous recalculation for the narrated merchant. Requires merchant scope and `suppliers:manage`; a body cannot select another merchant. HTTP 202 acknowledges queueing, not completion.", "operationId": "recalculate-amazon-opportunities", "tags": [ "Sourcing" ], "responses": { "202": { "description": "Recalculation queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "merchant_uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued" ] } }, "additionalProperties": false, "required": [ "merchant_uuid", "status" ] } }, "additionalProperties": false, "required": [ "data" ] } } } }, "400": { "description": "The narrated service provider is not connected to the merchant", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant": { "type": "string" } }, "required": [ "merchant" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": { "$ref": "#/components/schemas/Page" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PerPage" } } ], "responses": { "200": { "description": "A successful response returning the paginated list of inventory items", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryItem" } } }, "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, "fnskus": [ "X008VSER78", "X00U2E5ZYE" ], "fnsku": "X008VSER78", "asin": "B014IA92I8", "searchableIdentifiers": "B014IA92I8,X008VSER78,X00U2E5ZYE,3495184061393", "images": [], "identifiers": [] } ], "per_page": 500, "total": 37 } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } }, "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": { "$ref": "#/components/schemas/InventoryItem" } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } }, "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" }, "page": { "$ref": "#/components/schemas/Page" }, "per_page": { "$ref": "#/components/schemas/PerPage" }, "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": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryItem" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryItem" } } }, "required": [ "data", "items" ] } ] }, "examples": { "example": { "value": { "current_page": 1, "data": [ { "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, "fnskus": [ "X00U2E5ZYE", "X008VSER78" ], "fnsku": "X00U2E5ZYE", "asin": "B07611F2KY", "images": [], "identifiers": [], "company_services": [] } ], "first_page_url": "https://example.com/api/inventory/search?page=1", "from": 1, "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, "fnskus": [ "X00U2E5ZYE", "X008VSER78" ], "fnsku": "X00U2E5ZYE", "asin": "B07611F2KY", "images": [], "identifiers": [], "company_services": [] } ], "last_page": 1, "last_page_url": "https://example.com/api/inventory/search?page=1", "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://example.com/api/inventory/search?page=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "next_page_url": null, "path": "https://example.com/api/inventory/search", "per_page": 10, "prev_page_url": null, "to": 1, "total": 1 } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } }, "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": "#/components/schemas/InventoryItem" } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } }, "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": "#/components/schemas/InventoryItem" } }, "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, "fnskus": [], "fnsku": "", "asin": "", "searchableIdentifiers": "", "images": [], "identifiers": [] } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } }, "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": "#/components/schemas/Page" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PerPage" } } ], "responses": { "200": { "description": "A successful response returning the paginated list of inbound shipments", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InboundShipment" } } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } }, "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": "#/components/schemas/Page" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PerPage" } } ], "responses": { "200": { "description": "A successful response returning the paginated list of archived inbound shipments", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InboundShipment" } } }, "required": [ "data" ] } ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } }, "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": "#/components/schemas/InboundShipment" }, { "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } }, "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": { "$ref": "#/components/schemas/InboundShipment" } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } }, "tags": [ "Inbound Shipments" ] }, "delete": { "summary": "Delete an inbound shipment", "description": "Delete an inbound shipment by its ID", "operationId": "delete-inbound-shipment", "parameters": [ { "name": "inbound_shipment", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the inbound shipment", "example": 1001 } } ], "responses": { "204": { "description": "The inbound shipment was successfully deleted" }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "409": { "description": "Conflict — another request is updating this inbound shipment; retry shortly" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } }, "tags": [ "Inbound Shipments" ] } }, "/shipments/inbound/{inbound_shipment}/add-tracking": { "post": { "summary": "Add tracking to an inbound shipment", "description": "Add tracking numbers from one carrier to an inbound shipment. The numbers are added alongside the shipment's existing tracking; a number the shipment already has is left unchanged. When no carrier is provided, the shipment is not changed.", "operationId": "add-inbound-shipment-tracking", "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", "description": "The carrier the tracking numbers belong to", "enum": [ "fedex", "ups", "usps", "shippo", "canada_post", "dhl_express", "ontrac", "royal_mail", "parcel_force", "dpd_uk", "dhl_uk", "evri", "other" ], "example": "ups" }, "tracking_numbers": { "type": "array", "description": "The tracking numbers to add. Required when carrier is provided.", "items": { "type": "string", "description": "A tracking number made of letters and digits only", "maxLength": 255, "example": "1Z999AA10123456784" } } } } } } }, "responses": { "200": { "description": "The tracking numbers were successfully added", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A success message", "example": "Shipment updated." } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Shipment updated." } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } }, "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": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/OutboundShipment" }, { "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/OutboundShipment" }, { "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } } }, "/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": [ { "$ref": "#/components/schemas/OutboundShipment" }, { "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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" }, "moves": [], "company_services": [] } ] } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } } } }, "/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": "#/components/schemas/FbaTransportV2024Plan" } } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } }, "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": { "$ref": "#/components/schemas/FbaTransportV2024Plan" } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/FbaTransportV2024Plan" } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/request-package-labels": { "post": { "summary": "Request package labels", "operationId": "request-fba-transport-v2024-package-labels", "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": { "shipment_id": { "type": "string", "example": "shipment-1" } }, "required": [ "shipment_id" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Shipping labels have been downloaded successfully." } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Shipping labels have been downloaded successfully." } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/request-box-labels": { "post": { "summary": "Request box labels", "operationId": "request-fba-transport-v2024-box-labels", "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": { "box_group_id": { "type": [ "string", "null" ] }, "shipment_id": { "type": "string", "example": "shipment-1" }, "box_numbers": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 1, "example": 1 } }, "sort_by_internal_number": { "type": [ "boolean", "null" ], "example": false } }, "required": [ "shipment_id" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requesting box labels" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Requesting box labels" } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/request-individual-box-labels": { "post": { "summary": "Request individual box labels", "operationId": "request-fba-transport-v2024-individual-box-labels", "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": { "shipment_id": { "type": "string", "example": "shipment-1" }, "box_numbers": { "type": "array", "items": { "type": "integer", "minimum": 1, "example": 1 } }, "sort_by_internal_number": { "type": [ "boolean", "null" ], "example": false } }, "required": [ "shipment_id", "box_numbers" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requesting individual box labels" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Requesting individual box labels" } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/request-pallet-labels": { "post": { "summary": "Request pallet labels", "operationId": "request-fba-transport-v2024-pallet-labels", "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": { "pallets": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer", "example": 1 } }, "required": [ "number" ] } }, "shipment_id": { "type": "string", "example": "shipment-1" } }, "required": [ "pallets", "shipment_id" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Pallet labels requested" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Pallet labels requested" } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/download-pallet-labels": { "post": { "summary": "Download pallet labels", "operationId": "download-fba-transport-v2024-pallet-labels", "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": { "shipment_id": { "type": "string", "example": "shipment-1" } }, "required": [ "shipment_id" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Pallet labels downloaded" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Pallet labels downloaded" } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/request-bill-of-lading": { "post": { "summary": "Request bill of lading", "operationId": "request-fba-transport-v2024-bill-of-lading", "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": { "shipment_id": { "type": "string", "example": "shipment-1" } }, "required": [ "shipment_id" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requesting bill of lading" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Requesting bill of lading" } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/labels/{label_id}/resize-to-4x6": { "post": { "summary": "Resize a shipment label to 4x6", "operationId": "resize-fba-transport-v2024-label-to-4x6", "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": "label_id", "in": "path", "required": true, "schema": { "type": "string", "example": "019b2286-9fee-71de-9f64-154824d3aa4d" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shipment_id": { "type": "string", "example": "shipment-1" }, "sort_by_internal_number": { "type": [ "boolean", "null" ], "example": false } }, "required": [ "shipment_id" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Generating resized labels, please wait 2-3 minutes for the process to complete" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Generating resized labels, please wait 2-3 minutes for the process to complete" } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/BoxGroupItem" } } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": { "$ref": "#/components/schemas/BoxGroupItem" } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/BoxGroupItem" }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/add-carton-request-to-submission": { "post": { "summary": "Add carton requests to a packing submission", "operationId": "add-fba-transport-v2024-carton-request-to-submission", "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": { "packing_group_ids": { "type": "array", "items": { "type": "string", "example": "packing-group-1" } } }, "required": [ "packing_group_ids" ] }, "examples": { "example": { "value": { "packing_group_ids": [ "packing-group-1" ] } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Packing information set successfully" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Packing information set successfully" } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/generate-packing-options": { "post": { "summary": "Generate packing options for an FBA plan", "operationId": "generate-fba-transport-v2024-packing-options", "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": "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/packing-options": { "get": { "summary": "Fetch packing options from Amazon", "operationId": "fetch-fba-transport-v2024-packing-options", "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" } } ], "responses": { "200": { "description": "Packing options fetched and stored on the plan successfully." }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/confirm-packing-option": { "post": { "summary": "Confirm a packing option with Amazon", "operationId": "confirm-fba-transport-v2024-packing-option", "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" }, "packing_option_id": { "type": "string", "example": "packing-option-1" } }, "required": [ "plan_id", "packing_option_id" ] }, "examples": { "example": { "value": { "plan_id": "019953ae-7a0d-7342-956a-881dcdbe42ad", "packing_option_id": "packing-option-1" } } } } } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/packing-group-items": { "get": { "summary": "Fetch packing group items from Amazon", "operationId": "fetch-fba-transport-v2024-packing-group-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": "plan_id", "in": "query", "required": true, "schema": { "type": "string", "description": "The ID of the FBA transport v2024 plan. Use the same value as the `plan` path parameter (the Conveyr plan UUID).", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } }, { "name": "packing_option_id", "in": "query", "required": true, "schema": { "type": "string", "description": "The Conveyr UUID of the packing option — i.e. the `id` field of a packing option from the packing-options response, NOT its `packing_option_id` field (which is Amazon's identifier). Passing Amazon's `packing_option_id` here will not match and the request will fail.", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } }, { "name": "packing_group_id", "in": "query", "required": true, "schema": { "type": "string", "description": "The packing group's identifier — i.e. the `id` field of an entry in the packing option's `packing_groups` array from the packing-options response. Unlike `packing_option_id`, this value is Amazon's own packing group ID (there is no separate Conveyr UUID for packing groups).", "example": "packing-group-1" } } ], "responses": { "200": { "description": "Packing group items fetched and stored successfully." }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/mark-packing-option-as-confirmed": { "post": { "summary": "Mark a packing option as confirmed", "operationId": "mark-fba-transport-v2024-packing-option-as-confirmed", "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" }, "packing_option_id": { "type": "string", "example": "packing-option-1" } }, "required": [ "plan_id", "packing_option_id" ] }, "examples": { "example": { "value": { "plan_id": "019953ae-7a0d-7342-956a-881dcdbe42ad", "packing_option_id": "packing-option-1" } } } } } }, "responses": { "200": { "description": "Packing option marked as confirmed successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Packing option confirmed successfully" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Packing option confirmed successfully" } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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" }, "idempotency_key": { "type": [ "string", "null" ], "description": "Stable client key for returning the existing operation when retrying the same confirm request", "maxLength": 255, "example": "confirm-transportation:FbaTransport_ConfirmTransportationOptions_019953ae" }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/get-shipment": { "get": { "summary": "Fetch shipments for a placement option from Amazon", "operationId": "get-fba-transport-v2024-shipment", "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": "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": "placement-option-1" } } ], "responses": { "200": { "description": "A successful response returning shipments", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "019b2286-9fee-71de-9f64-154824d3aa4d" }, "shipment_id": { "type": "string", "example": "shipment-1" }, "amazon_reference_id": { "type": [ "string", "null" ], "example": "AMZN123" }, "destination": { "type": "object", "properties": {} }, "source": { "type": "object", "properties": {} }, "status": { "type": [ "string", "null" ], "example": "WORKING" }, "shipment_confirmation_id": { "type": [ "string", "null" ], "example": "FBA123" }, "first_availability_date": { "type": [ "string", "null" ], "example": "2026-05-15T00:00:00.000000Z" }, "transport_mode_preference": { "type": [ "string", "null" ], "example": "PARTNERED_GROUND_SMALL_PARCEL" }, "tracking_details": { "type": "object", "properties": {} }, "contact_information": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone_number": { "type": [ "string", "null" ] } } }, "freight_information": { "type": "object", "properties": { "freight_class": { "type": [ "string", "null" ] }, "declaredValue": { "type": "object", "properties": {} } } }, "selected_transportation_option_id": { "type": [ "string", "null" ] }, "selected_delivery_window": { "type": "object", "properties": {} }, "pallets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "length_mm": { "type": "integer" }, "width_mm": { "type": "integer" }, "height_mm": { "type": "integer" }, "weight_gm": { "type": "integer" }, "repeat": { "type": "integer" }, "stackable": { "type": "boolean" } } } }, "box_groups": { "type": "array", "items": { "$ref": "#/components/schemas/ShipmentBoxGroup" } }, "boxes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "box_group_id": { "type": "string" }, "amazon_box_id": { "type": [ "string", "null" ] }, "box_number": { "type": "integer" } } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "plan_item_id": { "type": "string" }, "shipment_id": { "type": "string" }, "quantity": { "type": "integer" } } } }, "delivery_window_options": { "type": "array", "items": { "type": "object", "properties": {} } }, "transportation_options": { "type": "array", "items": { "type": "object", "properties": {} } } }, "required": [ "id", "shipment_id", "contact_information", "freight_information", "pallets", "box_groups", "boxes", "items", "delivery_window_options", "transportation_options" ] } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/list-shipment-boxes": { "get": { "summary": "List shipment boxes", "operationId": "list-fba-transport-v2024-shipment-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": "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": "placement-option-1" } }, { "name": "shipment_id", "in": "query", "required": true, "schema": { "type": "string", "example": "shipment-1" } } ], "responses": { "200": { "description": "A successful response returning shipment box groups", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShipmentBoxGroup" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/list-shipment-items": { "get": { "summary": "Fetch shipment items from Amazon", "operationId": "list-fba-transport-v2024-shipment-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": "placement_option_id", "in": "query", "required": true, "schema": { "type": "string", "example": "placement-option-1" } }, { "name": "shipment_id", "in": "query", "required": true, "schema": { "type": "string", "example": "shipment-1" } } ], "responses": { "200": { "description": "Shipment items fetched and stored successfully." }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/update": { "post": { "summary": "Update an FBA transport v2024 plan from Amazon", "operationId": "update-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": "019953ae-7a0d-7342-956a-881dcdbe42ad" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "examples": { "example": { "value": {} } } } } }, "responses": { "200": { "description": "Plan updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/update-packing-info-known": { "post": { "summary": "Update whether packing information is known", "operationId": "update-fba-transport-v2024-packing-info-known", "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": { "is_packing_info_known": { "type": "boolean", "example": true } }, "required": [ "is_packing_info_known" ] }, "examples": { "example": { "value": { "is_packing_info_known": true } } } } } }, "responses": { "200": { "description": "Packing workflow updated successfully." }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/update-shipment-name": { "post": { "summary": "Update an FBA shipment name", "operationId": "update-fba-transport-v2024-shipment-name", "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": { "shipment_id": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000001" }, "name": { "type": "string", "maxLength": 40, "example": "North dock shipment" } }, "required": [ "shipment_id", "name" ] } } } }, "responses": { "204": { "description": "Shipment name updated successfully." }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/change-using-2d-barcodes": { "post": { "summary": "Change whether a plan uses 2D barcodes", "operationId": "change-fba-transport-v2024-using-2d-barcodes", "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": { "using_2d_barcodes": { "type": "boolean", "example": true } }, "required": [ "using_2d_barcodes" ] }, "examples": { "example": { "value": { "using_2d_barcodes": true } } } } } }, "responses": { "200": { "description": "2D barcode setting updated successfully." }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/set-boxes-ids": { "get": { "summary": "Set Amazon box IDs for plan boxes", "operationId": "set-fba-transport-v2024-plan-box-ids", "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" } } ], "responses": { "202": { "description": "Boxes were assigned and saved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Boxes are assigned for the shipment." } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Boxes are assigned for the shipment." } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/pallets": { "post": { "summary": "Create a pallet for a shipment", "operationId": "create-fba-transport-v2024-pallet", "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": { "placement_option_id": { "type": "string", "example": "placement-option-1" }, "shipment_id": { "type": "string", "example": "shipment-1" }, "length_mm": { "type": "integer", "minimum": 1, "example": 1200 }, "width_mm": { "type": "integer", "minimum": 1, "example": 1000 }, "height_mm": { "type": "integer", "minimum": 1, "example": 1500 }, "weight_gm": { "type": "integer", "minimum": 1, "example": 25000 }, "repeat": { "type": "integer", "minimum": 1, "example": 1 }, "stackable": { "type": "boolean", "example": true } }, "required": [ "placement_option_id", "shipment_id", "length_mm", "width_mm", "height_mm", "weight_gm", "repeat", "stackable" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Pallet created" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Pallet created" } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/pallets/{pallet_id}": { "put": { "summary": "Update a shipment pallet", "operationId": "update-fba-transport-v2024-pallet", "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": "pallet_id", "in": "path", "required": true, "schema": { "type": "string", "example": "019b2286-9fee-71de-9f64-154824d3aa4d" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "placement_option_id": { "type": "string", "example": "placement-option-1" }, "shipment_id": { "type": "string", "example": "shipment-1" }, "length_mm": { "type": "integer", "minimum": 1, "example": 1200 }, "width_mm": { "type": "integer", "minimum": 1, "example": 1000 }, "height_mm": { "type": "integer", "minimum": 1, "example": 1500 }, "weight_gm": { "type": "integer", "minimum": 1, "example": 25000 }, "repeat": { "type": "integer", "minimum": 1, "example": 1 }, "stackable": { "type": "boolean", "example": true } }, "required": [ "placement_option_id", "shipment_id", "length_mm", "width_mm", "height_mm", "weight_gm", "repeat", "stackable" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Pallet updated" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Pallet updated" } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } }, "delete": { "summary": "Remove a shipment pallet", "operationId": "remove-fba-transport-v2024-pallet", "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": "pallet_id", "in": "path", "required": true, "schema": { "type": "string", "example": "019b2286-9fee-71de-9f64-154824d3aa4d" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "placement_option_id": { "type": "string", "example": "placement-option-1" }, "shipment_id": { "type": "string", "example": "shipment-1" } }, "required": [ "placement_option_id", "shipment_id" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Pallet removed" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Pallet removed" } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/contact-information": { "get": { "summary": "Get shipment contact information", "operationId": "get-fba-transport-v2024-contact-information", "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": "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": "placement-option-1" } }, { "name": "shipment_id", "in": "query", "required": true, "schema": { "type": "string", "example": "shipment-1" } } ], "responses": { "200": { "description": "Contact information response.", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/update-contact-information": { "post": { "summary": "Update shipment contact information", "operationId": "update-fba-transport-v2024-contact-information", "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", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" }, "placement_option_id": { "type": "string", "example": "placement-option-1" }, "shipment_id": { "type": "string", "example": "shipment-1" }, "email": { "type": "string", "example": "ops@example.com" }, "name": { "type": "string", "example": "Ops Contact" }, "phone_number": { "type": "string", "example": "1234567890" } }, "required": [ "plan_id", "placement_option_id", "shipment_id" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Contact information set successfully" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Contact information set successfully" } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/freight-information": { "get": { "summary": "Get shipment freight information", "operationId": "get-fba-transport-v2024-freight-information", "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": "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": "placement-option-1" } }, { "name": "shipment_id", "in": "query", "required": true, "schema": { "type": "string", "example": "shipment-1" } } ], "responses": { "200": { "description": "Freight information response.", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/update-freight-information": { "post": { "summary": "Update shipment freight information", "operationId": "update-fba-transport-v2024-freight-information", "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", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" }, "placement_option_id": { "type": "string", "example": "placement-option-1" }, "shipment_id": { "type": "string", "example": "shipment-1" }, "freight_class": { "type": [ "string", "null" ], "enum": [ "NONE", "FC_50", "FC_55", "FC_60", "FC_65", "FC_70", "FC_77_5", "FC_85", "FC_92_5", "FC_100", "FC_110", "FC_125", "FC_150", "FC_175", "FC_200", "FC_250", "FC_300", "FC_400", "FC_500" ], "example": "FC_100" }, "amount": { "type": [ "string", "null" ], "example": "100.00" }, "code": { "type": [ "string", "null" ], "example": "USD" } }, "required": [ "plan_id", "placement_option_id", "shipment_id" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Freight information updated successfully" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Freight information updated successfully" } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/set-first-availability-date": { "post": { "summary": "Set shipment first availability date", "operationId": "set-fba-transport-v2024-shipment-first-availability-date", "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", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" }, "placement_option_id": { "type": "string", "example": "placement-option-1" }, "shipment_id": { "type": "string", "example": "shipment-1" }, "first_availability_date": { "type": "string", "example": "2026-05-15T00:00:00Z" } }, "required": [ "plan_id", "placement_option_id", "shipment_id", "first_availability_date" ] } } } }, "responses": { "200": { "description": "First availability date updated successfully." }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/set-transport-mode-preference": { "post": { "summary": "Set shipment transport mode preference", "operationId": "set-fba-transport-v2024-transport-mode-preference", "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", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" }, "placement_option_id": { "type": "string", "example": "placement-option-1" }, "shipment_id": { "type": "string", "example": "shipment-1" }, "transport_mode_preference": { "type": "string", "enum": [ "PARTNERED_GROUND_SMALL_PARCEL", "PARTNERED_FREIGHT_LTL", "NON_PARTNERED_GROUND_SMALL_PARCEL", "NON_PARTNERED_FREIGHT_LTL" ], "example": "PARTNERED_GROUND_SMALL_PARCEL" } }, "required": [ "plan_id", "placement_option_id", "shipment_id", "transport_mode_preference" ] } } } }, "responses": { "200": { "description": "Transport mode preference updated successfully." }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/update-tracking-small-details": { "post": { "summary": "Update small parcel tracking details", "operationId": "update-fba-transport-v2024-tracking-small-details", "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", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" }, "shipment_id": { "type": "string", "example": "shipment-1" }, "box_tracking_ids": { "type": "array", "items": { "type": "object", "properties": { "amazon_box_id": { "type": "string", "example": "FBA1U000001" }, "tracking_id": { "type": "string", "example": "1Z999AA10123456784" } }, "required": [ "amazon_box_id", "tracking_id" ] } } }, "required": [ "plan_id", "shipment_id", "box_tracking_ids" ] } } } }, "responses": { "200": { "description": "Small parcel tracking details updated successfully." }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/update-tracking-ltl-details": { "post": { "summary": "Update LTL tracking details", "operationId": "update-fba-transport-v2024-tracking-ltl-details", "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", "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" }, "shipment_id": { "type": "string", "example": "shipment-1" }, "bill_of_lading_number": { "type": "string", "example": "BOL123" }, "freight_bill_number": { "type": "array", "items": { "type": "string", "example": "FB123" } } }, "required": [ "plan_id", "shipment_id", "freight_bill_number" ] } } } }, "responses": { "200": { "description": "LTL tracking details updated successfully." }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/cancel-plan": { "post": { "summary": "Cancel an FBA transport plan with Amazon", "operationId": "cancel-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": "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": "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/cancel-plan-checker": { "post": { "summary": "Check whether canceling an FBA transport plan may incur fees", "operationId": "check-cancel-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": "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": "Cancel fee warning response.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": {} }, { "type": "array", "items": { "type": "string", "example": "The seller's account is charged for the shipping cost for each shipment exceed 24 hours for GroundSmallParcel and One hour for FTL/LTL" } } ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/mark-plan-as-canceled": { "post": { "summary": "Mark an FBA transport plan as canceled", "operationId": "mark-fba-transport-v2024-plan-as-canceled", "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": {} }, "examples": { "example": { "value": {} } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Plan canceled successfully" } }, "required": [ "message" ] }, "examples": { "example": { "value": { "message": "Plan canceled successfully" } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/pick-list": { "get": { "summary": "Generate a pick list PDF", "operationId": "get-fba-transport-v2024-pick-list", "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": "placement_option_id", "in": "query", "required": true, "schema": { "type": "string", "example": "placement-option-1" } }, { "name": "shipment_id", "in": "query", "required": true, "schema": { "type": "string", "example": "shipment-1" } } ], "responses": { "200": { "description": "A successful response returning a generated PDF URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Pick list generated" }, "url": { "type": "string", "format": "uri", "example": "https://example.com/list.pdf" } }, "required": [ "message", "url" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/plans/{plan}/pack-list": { "get": { "summary": "Generate a pack list PDF", "operationId": "get-fba-transport-v2024-pack-list", "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": "placement_option_id", "in": "query", "required": true, "schema": { "type": "string", "example": "placement-option-1" } }, { "name": "shipment_id", "in": "query", "required": true, "schema": { "type": "string", "example": "shipment-1" } } ], "responses": { "200": { "description": "A successful response returning a generated PDF URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Pack list generated" }, "url": { "type": "string", "format": "uri", "example": "https://example.com/list.pdf" } }, "required": [ "message", "url" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": { "$ref": "#/components/schemas/Operation" } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } } } }, "/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": "#/components/schemas/Operation" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } } } }, "/fba-transport/v2024/operations": { "get": { "summary": "List FBA transport operations", "operationId": "list-fba-transport-v2024-operations", "tags": [ "FBA Transport" ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Search operations by ID", "example": "019953ae-8047-71b6-8214-cafa0b1eff32" } }, { "name": "page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Page" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PerPage" } } ], "responses": { "200": { "description": "A successful response returning the paginated list of FBA transport operations", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Operation" } } }, "required": [ "data" ] } ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } } }, "/fba-transport/v2024/item-eligibility": { "get": { "summary": "Fetch stored FBA item eligibility", "operationId": "fetch-fba-transport-v2024-item-eligibility", "tags": [ "FBA Transport" ], "parameters": [ { "name": "channel_id", "in": "query", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "asins", "in": "query", "required": true, "schema": { "type": "array", "items": { "type": "string", "example": "B00ZB18SIF" } } } ], "responses": { "200": { "description": "A successful response returning stored item eligibility records", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "019b2286-9fee-71de-9f64-154824d3aa4d" }, "channel_id": { "type": "integer", "example": 1 }, "asin": { "type": "string", "example": "B00ZB18SIF" }, "program": { "type": "string", "example": "INBOUND" }, "is_eligible": { "type": "boolean", "example": true }, "ineligibility_reasons": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "id", "channel_id", "asin", "program", "is_eligible" ] } } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": [ { "id": "019b2286-9fee-71de-9f64-154824d3aa4d", "channel_id": 1, "asin": "B00ZB18SIF", "program": "INBOUND", "is_eligible": true, "ineligibility_reasons": [] } ] } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/fetch-item-eligibility": { "get": { "summary": "Fetch FBA item eligibility from Amazon", "operationId": "fetch-fba-transport-v2024-item-eligibility-from-amazon", "tags": [ "FBA Transport" ], "parameters": [ { "name": "channel_id", "in": "query", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "asin", "in": "query", "required": true, "schema": { "type": "string", "example": "B00ZB18SIF" } } ], "responses": { "200": { "description": "A successful response returning the fetched item eligibility record", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "example": "019b2286-9fee-71de-9f64-154824d3aa4d" }, "channel_id": { "type": "integer", "example": 1 }, "asin": { "type": "string", "example": "B00ZB18SIF" }, "program": { "type": "string", "example": "INBOUND" }, "is_eligible": { "type": "boolean", "example": true }, "ineligibility_reasons": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "id", "channel_id", "asin", "program", "is_eligible" ] }, { "type": "null" } ] } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "id": "019b2286-9fee-71de-9f64-154824d3aa4d", "channel_id": 1, "asin": "B00ZB18SIF", "program": "INBOUND", "is_eligible": true, "ineligibility_reasons": [] } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/item-prep-details": { "get": { "summary": "Fetch FBA item prep details", "operationId": "fetch-fba-transport-v2024-item-prep-details", "tags": [ "FBA Transport" ], "parameters": [ { "name": "channel_id", "in": "query", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "mskus", "in": "query", "required": true, "schema": { "type": "array", "items": { "type": "string", "example": "Mini-Porta-276810" } } }, { "name": "fresh", "in": "query", "required": false, "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "A successful response returning item prep details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "019b2286-9fee-71de-9f64-154824d3aa4d" }, "channel_id": { "type": "integer", "example": 1 }, "msku": { "type": "string", "example": "Mini-Porta-276810" }, "allOwnersConstraint": { "type": [ "string", "null" ] }, "labelOwnerConstraint": { "type": [ "string", "null" ], "example": "SELLER" }, "prepOwnerConstraint": { "type": [ "string", "null" ], "example": "SELLER" }, "prepCategory": { "type": "string", "enum": [ "ADULT", "BABY", "FC_PROVIDED", "FRAGILE", "GRANULAR", "HANGER", "LIQUID", "PERFORATED", "SET", "SHARP", "SMALL", "TEXTILE", "UNKNOWN", "NONE" ], "example": "NONE" }, "prepTypes": { "type": "array", "items": { "type": "string", "enum": [ "ITEM_LABELING", "ITEM_BUBBLEWRAP", "ITEM_POLYBAGGING", "ITEM_TAPING", "ITEM_BLACK_SHRINKWRAP", "ITEM_HANG_GARMENT", "ITEM_BOXING", "ITEM_SETCREAT", "ITEM_RMOVHANG", "ITEM_SUFFOSTK", "ITEM_CAP_SEALING", "ITEM_DEBUNDLE", "ITEM_SETSTK", "ITEM_SIOC", "ITEM_NO_PREP", "ADULT", "BABY", "TEXTILE", "HANGER", "FRAGILE", "LIQUID", "SHARP", "SMALL", "PERFORATED", "GRANULAR", "SET", "FC_PROVIDED", "UNKNOWN", "NONE" ], "example": "ITEM_NO_PREP" } } }, "required": [ "id", "channel_id", "msku", "prepCategory", "prepTypes" ] } } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": [ { "id": "019b2286-9fee-71de-9f64-154824d3aa4d", "channel_id": 1, "msku": "Mini-Porta-276810", "allOwnersConstraint": null, "labelOwnerConstraint": "SELLER", "prepOwnerConstraint": "SELLER", "prepCategory": "NONE", "prepTypes": [ "ITEM_NO_PREP" ] } ] } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } }, "post": { "summary": "Set FBA item prep details", "operationId": "set-fba-transport-v2024-item-prep-details", "tags": [ "FBA Transport" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel_id": { "type": "integer", "example": 1 }, "prep_details": { "type": "array", "items": { "type": "object", "properties": { "msku": { "type": "string", "example": "Mini-Porta-276810" }, "prep_category": { "type": "string", "enum": [ "ADULT", "BABY", "FC_PROVIDED", "FRAGILE", "GRANULAR", "HANGER", "LIQUID", "PERFORATED", "SET", "SHARP", "SMALL", "TEXTILE", "UNKNOWN", "NONE" ], "example": "NONE" }, "prep_types": { "type": "array", "items": { "type": "string", "enum": [ "ITEM_LABELING", "ITEM_BUBBLEWRAP", "ITEM_POLYBAGGING", "ITEM_TAPING", "ITEM_BLACK_SHRINKWRAP", "ITEM_HANG_GARMENT", "ITEM_BOXING", "ITEM_SETCREAT", "ITEM_RMOVHANG", "ITEM_SUFFOSTK", "ITEM_CAP_SEALING", "ITEM_DEBUNDLE", "ITEM_SETSTK", "ITEM_SIOC", "ITEM_NO_PREP", "ADULT", "BABY", "TEXTILE", "HANGER", "FRAGILE", "LIQUID", "SHARP", "SMALL", "PERFORATED", "GRANULAR", "SET", "FC_PROVIDED", "UNKNOWN", "NONE" ], "example": "ITEM_NO_PREP" } } }, "required": [ "msku", "prep_category" ] } } }, "required": [ "channel_id", "prep_details" ] }, "examples": { "example": { "value": { "channel_id": 1, "prep_details": [ { "msku": "Mini-Porta-276810", "prep_category": "NONE", "prep_types": [ "ITEM_NO_PREP" ] } ] } } } } } }, "responses": { "200": { "description": "A successful response returning the operation ID or a retry message", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation_id": { "type": "string", "example": "019953ae-8047-71b6-8214-cafa0b1eff32" }, "message": { "type": "string", "example": "Amazon returned errors that were automatically handled, please try this request again." } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/list-v2024-plans": { "get": { "summary": "List Amazon FBA inbound plans", "operationId": "list-amazon-fba-transport-v2024-plans", "tags": [ "FBA Transport" ], "parameters": [ { "name": "warehouse_id", "in": "query", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ACTIVE", "VOIDED", "SHIPPED", "ERRORED" ], "example": "ACTIVE" } }, { "name": "pagination_token", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "A successful response returning Amazon inbound plans", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2026-05-14T12:00:00Z" }, "last_updated_at": { "type": "string", "example": "2026-05-14T12:30:00Z" }, "inbound_plan_id": { "type": "string", "example": "wf123" }, "marketplace_ids": { "type": "array", "items": { "type": "string", "example": "ATVPDKIKX0DER" } }, "name": { "type": "string", "example": "Imported inbound plan" }, "source_address": { "type": "object" }, "status": { "type": "string", "example": "ACTIVE" } }, "required": [ "created_at", "last_updated_at", "inbound_plan_id", "marketplace_ids", "name", "source_address", "status" ] } }, "pagination_token": { "type": [ "string", "null" ], "example": null } }, "required": [ "plans", "pagination_token" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/fba-transport/v2024/import-plan": { "get": { "summary": "Import an Amazon FBA inbound plan", "operationId": "import-fba-transport-v2024-plan", "tags": [ "FBA Transport" ], "parameters": [ { "name": "inbound_plan_id", "in": "query", "required": true, "schema": { "type": "string", "example": "wf123" } }, { "name": "channel_id", "in": "query", "required": true, "schema": { "type": "string", "example": "1" } }, { "name": "warehouse_id", "in": "query", "required": true, "schema": { "type": "integer", "example": 1 } }, { "name": "create_inbound", "in": "query", "required": true, "schema": { "type": "boolean", "example": true } } ], "responses": { "200": { "description": "A successful response returning the imported FBA transport plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/FbaTransportV2024Plan" } }, "required": [ "plan" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } } }, "/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": "#/components/schemas/Merchant" } } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": [ { "id": 1, "uuid": "550e8400-e29b-41d4-a716-446655440000", "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } }, "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": { "$ref": "#/components/schemas/Merchant" } }, "required": [ "message", "merchant" ] }, "examples": { "example": { "value": { "message": "Merchant created", "merchant": { "id": 35423, "uuid": "550e8400-e29b-41d4-a716-446655440000", "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Merchant" } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": { "id": 1, "uuid": "550e8400-e29b-41d4-a716-446655440000", "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/serviceProviders": { "get": { "summary": "List service providers", "description": "Returns every service provider the selected merchant is connected to. The merchant is taken from the `X-Selected-Client-Id` header; no service provider header is required.", "operationId": "list-service-providers", "tags": [ "Service Providers" ], "responses": { "200": { "description": "A successful response returning the list of connected service providers", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "The list of service providers the merchant is connected to", "items": { "type": "object", "description": "NOTE: The service provider resource uses camelCase keys as that is the existing API behaviour.", "properties": { "id": { "type": "integer", "description": "The unique identifier for the service provider", "example": 1 }, "uuid": { "type": "string", "description": "The UUID of the service provider", "example": "01930f3e-4a3e-7c1e-9a2b-2b6f0f4e8a11" }, "url": { "type": "string", "description": "The URL of the service provider's app, using its custom domain when one is configured and its subdomain on the platform domain otherwise", "example": "https://acmeprep.prepbusiness.com" }, "logo_file": { "type": [ "string", "null" ], "description": "The file name of the service provider's logo" }, "favicon_file": { "type": [ "string", "null" ], "description": "The file name of the service provider's favicon" }, "support_email": { "type": [ "string", "null" ], "description": "The support email address of the service provider", "example": "support@acmeprep.com" }, "name": { "type": "string", "description": "The name of the service provider", "example": "ACME Prep" }, "currency": { "type": "string", "description": "The ISO 4217 currency code the service provider bills in", "example": "USD" }, "available_permissions": { "type": "array", "description": "The permissions the service provider has granted to its merchants", "items": { "type": "string", "example": "createOutboundShipment" } } }, "required": [ "id", "uuid", "url", "logo_file", "favicon_file", "support_email", "name", "currency", "available_permissions" ] } } }, "required": [ "data" ] }, "examples": { "example": { "value": { "data": [ { "id": 1, "uuid": "01930f3e-4a3e-7c1e-9a2b-2b6f0f4e8a11", "url": "https://acmeprep.prepbusiness.com", "logo_file": null, "favicon_file": null, "support_email": "support@acmeprep.com", "name": "ACME Prep", "currency": "USD", "available_permissions": [ "createOutboundShipment" ] } ] } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } }, "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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/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": "#/components/schemas/PaginatedResponse" }, { "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://your-instance.example.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://your-instance.example.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": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } } }, "/workflows": { "get": { "summary": "List workflows", "operationId": "list-workflows", "tags": [ "Workflows" ], "parameters": [ { "name": "workflow_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "example": "FbaTransport_Autoplanner_abc123" }, "maxItems": 10 } }, { "name": "search_attributes[user_id]", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "example": 1 } }, { "name": "search_attributes[fba_plan_id]", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "A successful response returning workflows", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workflow" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/workflows/dispatch": { "post": { "summary": "Dispatch a workflow", "operationId": "dispatch-workflow", "tags": [ "Workflows" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "fbaTransport_copyBoxGroupsFromPlanToPlan", "fbaTransport_autoplanner", "fbaTransport_confirmTransportationOptions", "fbaTransport_confirmPlacementOption", "fbaTransport_splitPackingGroupsIntoPlans" ], "example": "fbaTransport_autoplanner" }, "input": { "type": "object", "description": "Workflow-specific input. Required fields depend on the selected type." }, "search_attributes": { "type": "object", "properties": { "fba_plan_id": { "type": [ "string", "null" ], "example": "019953ae-7a0d-7342-956a-881dcdbe42ad" } } } }, "required": [ "type" ] }, "examples": { "example": { "value": { "type": "fbaTransport_autoplanner", "input": { "plan_id": "019953ae-7a0d-7342-956a-881dcdbe42ad" }, "search_attributes": { "fba_plan_id": "019953ae-7a0d-7342-956a-881dcdbe42ad" } } } } } } }, "responses": { "200": { "description": "A successful response returning the dispatched workflow", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Workflow" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "/notifications/serviceProviders/senderDomains": { "get": { "summary": "Get the sender domain", "description": "Get the sending domain configured for the current service provider, or null when none is configured. A service provider may configure at most one sender domain.", "operationId": "get-sender-domain", "tags": [ "Sender Domains" ], "responses": { "200": { "description": "A successful response returning the sender domain, or null when none is configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "sender_domain": { "type": [ "object", "null" ], "description": "The configured sender domain, or null when the service provider has not registered one", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique UUID identifier for the sender domain", "example": "550e8400-e29b-41d4-a716-446655440000" }, "domain": { "type": "string", "description": "The registered sending domain, which signs outbound mail", "example": "mg.example.com" }, "from_email": { "type": "string", "format": "email", "description": "The address notifications are sent from once the domain is verified", "example": "info@example.com" }, "verification_status": { "type": "string", "description": "Whether the published DNS records have been confirmed. Rechecked automatically in the background; failed is terminal for this registration.", "enum": [ "pending", "verified", "failed" ], "example": "pending" }, "dns_records": { "type": "array", "description": "The DNS records that must be published for the domain to verify", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The DNS record type", "example": "TXT" }, "name": { "type": "string", "description": "The DNS record name", "example": "mg.example.com" }, "value": { "type": "string", "description": "The DNS record value", "example": "v=spf1 include:mailgun.org ~all" }, "valid": { "type": "boolean", "description": "Whether this record has been observed as published", "example": false }, "priority": { "type": "string", "description": "The MX record priority. Only present on MX records.", "example": "10" } }, "required": [ "type", "name", "value", "valid" ] } } } } }, "required": [ "sender_domain" ] }, "examples": { "configured": { "value": { "sender_domain": { "id": "550e8400-e29b-41d4-a716-446655440000", "domain": "mg.example.com", "from_email": "info@example.com", "verification_status": "pending", "dns_records": [ { "type": "TXT", "name": "mg.example.com", "value": "v=spf1 include:mailgun.org ~all", "valid": false } ] } } }, "not-configured": { "value": { "sender_domain": null } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" } } }, "post": { "summary": "Register a sender domain", "description": "Register a sending domain for the current service provider and return the DNS records that must be published before it can be verified. Any existing sender domain for the service provider is replaced. The sending address must be on the registered domain, or on a domain that the registered domain is a subdomain of, so that DKIM signatures align with the From header.", "operationId": "create-sender-domain", "tags": [ "Sender Domains" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "The domain to register for sending. A dedicated subdomain such as mg.example.com is recommended so that sending reputation is isolated.", "example": "mg.example.com" }, "from_email": { "type": "string", "format": "email", "description": "The address notifications are sent from. Must be aligned with the registered domain.", "example": "info@example.com" } }, "required": [ "domain", "from_email" ] } } } }, "responses": { "200": { "description": "A successful response returning the newly registered sender domain and the DNS records to publish", "content": { "application/json": { "schema": { "type": "object", "properties": { "sender_domain": { "$ref": "#/components/schemas/SenderDomain" } }, "required": [ "sender_domain" ] }, "examples": { "example": { "value": { "sender_domain": { "id": "550e8400-e29b-41d4-a716-446655440000", "domain": "mg.example.com", "from_email": "info@example.com", "verification_status": "pending", "dns_records": [ { "type": "TXT", "name": "mg.example.com", "value": "v=spf1 include:mailgun.org ~all", "valid": false }, { "type": "TXT", "name": "k1._domainkey.mg.example.com", "value": "k=rsa; p=MIGfMA0GCSqGSIb3", "valid": false } ] } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "409": { "description": "Conflict — another registration for this service provider is in progress" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } }, "patch": { "summary": "Update the sending address", "description": "Change the address notifications are sent from without re-registering the domain or republishing DNS records. The address must remain aligned with the registered domain.", "operationId": "update-sender-domain", "tags": [ "Sender Domains" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_email": { "type": "string", "format": "email", "description": "The address notifications are sent from. Must be aligned with the registered domain.", "example": "noreply@example.com" } }, "required": [ "from_email" ] } } } }, "responses": { "200": { "description": "A successful response returning the updated sender domain", "content": { "application/json": { "schema": { "type": "object", "properties": { "sender_domain": { "$ref": "#/components/schemas/SenderDomain" } }, "required": [ "sender_domain" ] }, "examples": { "example": { "value": { "sender_domain": { "id": "550e8400-e29b-41d4-a716-446655440000", "domain": "mg.example.com", "from_email": "noreply@example.com", "verification_status": "verified", "dns_records": [ { "type": "TXT", "name": "mg.example.com", "value": "v=spf1 include:mailgun.org ~all", "valid": true } ] } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" }, "422": { "$ref": "#/components/schemas/UnprocessableEntity" } } }, "delete": { "summary": "Delete the sender domain", "description": "Remove the sender domain for the current service provider. Notifications fall back to being sent from the service provider's support email afterwards.", "operationId": "delete-sender-domain", "tags": [ "Sender Domains" ], "responses": { "200": { "description": "A successful response after deleting the sender domain", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example": { "value": {} } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } } } }, "/notifications/serviceProviders/senderDomains/verify": { "post": { "summary": "Verify the sender domain", "description": "Force an immediate check of the sender domain's DNS records and return the updated status. Verification is also retried automatically in the background after registration, so this is only needed to check sooner.", "operationId": "verify-sender-domain", "tags": [ "Sender Domains" ], "responses": { "200": { "description": "A successful response returning the sender domain with its refreshed verification status", "content": { "application/json": { "schema": { "type": "object", "properties": { "sender_domain": { "$ref": "#/components/schemas/SenderDomain" } }, "required": [ "sender_domain" ] }, "examples": { "example": { "value": { "sender_domain": { "id": "550e8400-e29b-41d4-a716-446655440000", "domain": "mg.example.com", "from_email": "info@example.com", "verification_status": "verified", "dns_records": [ { "type": "TXT", "name": "mg.example.com", "value": "v=spf1 include:mailgun.org ~all", "valid": true } ] } } } } } } }, "401": { "$ref": "#/components/schemas/Unauthorized" }, "403": { "$ref": "#/components/schemas/Forbidden" }, "404": { "$ref": "#/components/schemas/NotFound" } } } } }, "webhooks": { "channel.connected": { "post": { "summary": "channel.connected webhook", "description": "This webhook is sent to subscribed endpoints when the channel.connected event occurs.", "operationId": "webhook-channel-connected", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "channel.connected", "description": "Structured CloudEvent for the channel.connected webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "channel.connected" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the connected channel.", "example": 6001 }, "merchant_id": { "type": "integer", "description": "The merchant that owns the channel.", "example": 42 }, "type": { "type": "string", "description": "The channel type.", "example": "shopify" }, "nickname": { "type": [ "string", "null" ], "description": "The channel nickname.", "example": "Main Store" }, "is_active": { "type": "boolean", "description": "Whether the channel is active.", "example": true }, "account_id": { "type": [ "string", "null" ], "description": "The external channel account identifier.", "example": "store.example.com" } }, "required": [ "id", "merchant_id", "type", "nickname", "is_active", "account_id" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "fba_transport_plan.shipped": { "post": { "summary": "fba_transport_plan.shipped webhook", "description": "This webhook is sent to subscribed endpoints when the fba_transport_plan.shipped event occurs.", "operationId": "webhook-fba-transport-plan-shipped", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "fba_transport_plan.shipped", "description": "Structured CloudEvent for the fba_transport_plan.shipped webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "fba_transport_plan.shipped" ] }, "data": { "type": "object", "properties": { "plan_id": { "type": [ "integer", "string" ], "description": "The FBA transport plan identifier.", "example": 123 }, "outbound_shipment_id": { "type": "integer", "description": "The outbound shipment linked to the FBA transport plan.", "example": 7001 }, "merchant_id": { "type": "integer", "description": "The merchant that owns the plan.", "example": 42 } }, "required": [ "plan_id", "outbound_shipment_id", "merchant_id" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "inbound_shipment.created": { "post": { "summary": "inbound_shipment.created webhook", "description": "This webhook is sent to subscribed endpoints when the inbound_shipment.created event occurs.", "operationId": "webhook-inbound-shipment-created", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "inbound_shipment.created", "description": "Structured CloudEvent for the inbound_shipment.created webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "inbound_shipment.created" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the inbound shipment.", "example": 1001 }, "merchant_id": { "type": "integer", "description": "The merchant that owns the inbound shipment.", "example": 42 }, "warehouse_id": { "type": "integer", "description": "The destination warehouse for the inbound shipment.", "example": 5 } }, "required": [ "id", "merchant_id", "warehouse_id" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "inbound_shipment.items_updated": { "post": { "summary": "inbound_shipment.items_updated webhook", "description": "This webhook is sent to subscribed endpoints when the inbound_shipment.items_updated event occurs.", "operationId": "webhook-inbound-shipment-items-updated", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "inbound_shipment.items_updated", "description": "Structured CloudEvent for the inbound_shipment.items_updated webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "inbound_shipment.items_updated" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the inbound shipment.", "example": 1001 }, "merchant_id": { "type": "integer", "description": "The merchant that owns the inbound shipment.", "example": 42 }, "warehouse_id": { "type": "integer", "description": "The destination warehouse for the inbound shipment.", "example": 5 }, "expected_items": { "type": "array", "description": "Expected item lines for the inbound shipment.", "items": { "type": "object" }, "example": [] }, "actual_items": { "type": "array", "description": "Received sellable item lines for the inbound shipment.", "items": { "type": "object" }, "example": [] }, "unsellable_items": { "type": "array", "description": "Received unsellable item lines for the inbound shipment.", "items": { "type": "object" }, "example": [] } }, "required": [ "id", "merchant_id", "warehouse_id", "expected_items", "actual_items", "unsellable_items" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "inbound_shipment.name_updated": { "post": { "summary": "inbound_shipment.name_updated webhook", "description": "This webhook is sent to subscribed endpoints when the inbound_shipment.name_updated event occurs.", "operationId": "webhook-inbound-shipment-notes-updated", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "inbound_shipment.name_updated", "description": "Structured CloudEvent for the inbound_shipment.name_updated webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "inbound_shipment.name_updated" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the inbound shipment.", "example": 1001 }, "merchant_id": { "type": "integer", "description": "The merchant that owns the inbound shipment.", "example": 42 }, "warehouse_id": { "type": "integer", "description": "The destination warehouse for the inbound shipment.", "example": 5 } }, "required": [ "id", "merchant_id", "warehouse_id" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "inbound_shipment.notes_updated": { "post": { "summary": "inbound_shipment.notes_updated webhook", "description": "This webhook is sent to subscribed endpoints when the inbound_shipment.notes_updated event occurs.", "operationId": "webhook-inbound-shipment-notes-updated", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "inbound_shipment.notes_updated", "description": "Structured CloudEvent for the inbound_shipment.notes_updated webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "inbound_shipment.notes_updated" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the inbound shipment.", "example": 1001 }, "merchant_id": { "type": "integer", "description": "The merchant that owns the inbound shipment.", "example": 42 }, "warehouse_id": { "type": "integer", "description": "The destination warehouse for the inbound shipment.", "example": 5 } }, "required": [ "id", "merchant_id", "warehouse_id" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "inbound_shipment.received": { "post": { "summary": "inbound_shipment.received webhook", "description": "This webhook is sent to subscribed endpoints when the inbound_shipment.received event occurs.", "operationId": "webhook-inbound-shipment-received", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "inbound_shipment.received", "description": "Structured CloudEvent for the inbound_shipment.received webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "inbound_shipment.received" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the inbound shipment.", "example": 1001 }, "merchant_id": { "type": "integer", "description": "The merchant that owns the inbound shipment.", "example": 42 }, "warehouse_id": { "type": "integer", "description": "The destination warehouse for the inbound shipment.", "example": 5 } }, "required": [ "id", "merchant_id", "warehouse_id" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "inbound_shipment.shipped": { "post": { "summary": "inbound_shipment.shipped webhook", "description": "This webhook is sent to subscribed endpoints when the inbound_shipment.shipped event occurs.", "operationId": "webhook-inbound-shipment-shipped", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "inbound_shipment.shipped", "description": "Structured CloudEvent for the inbound_shipment.shipped webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "inbound_shipment.shipped" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the inbound shipment.", "example": 1001 }, "merchant_id": { "type": "integer", "description": "The merchant that owns the inbound shipment.", "example": 42 }, "warehouse_id": { "type": "integer", "description": "The destination warehouse for the inbound shipment.", "example": 5 } }, "required": [ "id", "merchant_id", "warehouse_id" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "inbound_shipment.tracking_updated": { "post": { "summary": "inbound_shipment.tracking_updated webhook", "description": "This webhook is sent to subscribed endpoints when the inbound_shipment.tracking_updated event occurs.", "operationId": "webhook-inbound-shipment-tracking-updated", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "inbound_shipment.tracking_updated", "description": "Structured CloudEvent for the inbound_shipment.tracking_updated webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "inbound_shipment.tracking_updated" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the inbound shipment.", "example": 1001 }, "merchant_id": { "type": "integer", "description": "The merchant that owns the inbound shipment.", "example": 42 }, "warehouse_id": { "type": "integer", "description": "The destination warehouse for the inbound shipment.", "example": 5 } }, "required": [ "id", "merchant_id", "warehouse_id" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "invoice.created": { "post": { "summary": "invoice.created webhook", "description": "This webhook is sent to subscribed endpoints when the invoice.created event occurs.", "operationId": "webhook-invoice-created", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "invoice.created", "description": "Structured CloudEvent for the invoice.created webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "invoice.created" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the invoice.", "example": 9001 }, "charger_id": { "type": "integer", "description": "The service provider issuing the invoice.", "example": 12 }, "chargee_id": { "type": "integer", "description": "The merchant being invoiced.", "example": 42 }, "currency": { "type": "string", "description": "The invoice currency code.", "example": "USD" }, "status": { "type": "string", "description": "The current invoice status.", "example": "draft" }, "total": { "type": "number", "description": "The invoice total.", "example": 123.45 } }, "required": [ "id", "charger_id", "chargee_id", "currency", "status", "total" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "item.identifier_created": { "post": { "summary": "item.identifier_created webhook", "description": "This webhook is sent to subscribed endpoints when the item.identifier_created event occurs.", "operationId": "webhook-item-identifier-created", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "item.identifier_created", "description": "Structured CloudEvent for the item.identifier_created webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "item.identifier_created" ] }, "data": { "type": "object", "properties": { "product_uuid": { "type": "string", "description": "The product UUID associated with the identifier.", "example": "00000000-0000-0000-0000-000000000001" }, "item_id": { "type": [ "integer", "null" ], "description": "The inventory item identifier, if linked.", "example": 5001 }, "item_sku": { "type": [ "string", "null" ], "description": "The inventory item merchant SKU, if linked.", "example": "SKU-001" }, "identifier_type": { "type": "string", "description": "The identifier type.", "example": "fnsku" }, "identifier": { "type": "string", "description": "The identifier value.", "example": "X001234567" } }, "required": [ "product_uuid", "item_id", "item_sku", "identifier_type", "identifier" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "item.stock_updated": { "post": { "summary": "item.stock_updated webhook", "description": "This webhook is sent to subscribed endpoints when the item.stock_updated event occurs.", "operationId": "webhook-item-stock-updated", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "item.stock_updated", "description": "Structured CloudEvent for the item.stock_updated webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "item.stock_updated" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the inventory item.", "example": 5001 }, "merchant_id": { "type": "integer", "description": "The merchant that owns the inventory item.", "example": 42 }, "merchant_sku": { "type": "string", "description": "The merchant SKU for the inventory item.", "example": "SKU-001" }, "identifiers": { "type": "array", "description": "Identifiers attached to the inventory item.", "items": { "type": "object" }, "example": [] } }, "required": [ "id", "merchant_id", "merchant_sku", "identifiers" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "merchant.added_to_service_provider": { "post": { "summary": "merchant.added_to_service_provider webhook", "description": "This webhook is sent to subscribed endpoints when the merchant.added_to_service_provider event occurs.", "operationId": "webhook-merchant-added-to-service-provider", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "merchant.added_to_service_provider", "description": "Structured CloudEvent for the merchant.added_to_service_provider webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "merchant.added_to_service_provider" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the merchant.", "example": 42 }, "name": { "type": "string", "description": "The merchant name.", "example": "Example Merchant" }, "notes": { "type": [ "string", "null" ], "description": "Notes stored on the merchant.", "example": "Priority merchant" }, "primaryEmail": { "type": [ "string", "null" ], "description": "The merchant primary email address.", "example": "merchant@example.com" }, "billingCycle": { "type": "string", "description": "The merchant billing cycle.", "example": "monthly" }, "enabled": { "type": "boolean", "description": "Whether the merchant is enabled.", "example": true } }, "required": [ "id", "name", "notes", "primaryEmail", "billingCycle", "enabled" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "merchant.user_added": { "post": { "summary": "merchant.user_added webhook", "description": "This webhook is sent to subscribed endpoints when the merchant.user_added event occurs.", "operationId": "webhook-merchant-user-added", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "merchant.user_added", "description": "Structured CloudEvent for the merchant.user_added webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "merchant.user_added" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the assigned user.", "example": 8001 }, "name": { "type": "string", "description": "The assigned user's display name.", "example": "Jane Doe" }, "merchant_id": { "type": "integer", "description": "The merchant the user was assigned to.", "example": 42 }, "merchant_name": { "type": "string", "description": "The merchant name.", "example": "Example Merchant" }, "user_role_on_merchant": { "type": "string", "description": "The user's role on the merchant.", "example": "owner" } }, "required": [ "id", "name", "merchant_id", "merchant_name", "user_role_on_merchant" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "order.created": { "post": { "summary": "order.created webhook", "description": "This webhook is sent to subscribed endpoints when the order.created event occurs.", "operationId": "webhook-order-created", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "order.created", "description": "Structured CloudEvent for the order.created webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "order.created" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the order.", "example": 3001 }, "customer": { "type": [ "object", "null" ], "description": "The customer associated with the order.", "example": { "id": 2001, "name": "Example Customer" } }, "order_items": { "type": "array", "description": "The order item lines.", "items": { "type": "object" }, "example": [] } }, "required": [ "id", "customer", "order_items" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "order.shipped": { "post": { "summary": "order.shipped webhook", "description": "This webhook is sent to subscribed endpoints when the order.shipped event occurs.", "operationId": "webhook-order-shipped", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "order.shipped", "description": "Structured CloudEvent for the order.shipped webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "order.shipped" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the order.", "example": 3001 }, "customer": { "type": [ "object", "null" ], "description": "The customer associated with the order.", "example": { "id": 2001, "name": "Example Customer" } }, "order_items": { "type": "array", "description": "The order item lines.", "items": { "type": "object" }, "example": [] }, "tracking_numbers": { "type": "array", "description": "Tracking data attached to the shipped order.", "items": { "type": "object" }, "example": [] } }, "required": [ "id", "customer", "order_items", "tracking_numbers" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "outbound_shipment.cancellation_denied": { "post": { "summary": "outbound_shipment.cancellation_denied webhook", "description": "This webhook is sent to subscribed endpoints when the outbound_shipment.cancellation_denied event occurs.", "operationId": "webhook-outbound-shipment-cancellation-denied", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "outbound_shipment.cancellation_denied", "description": "Structured CloudEvent for the outbound_shipment.cancellation_denied webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "outbound_shipment.cancellation_denied" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the outbound shipment.", "example": 7001 }, "merchant_id": { "type": "integer", "description": "The merchant that owns the outbound shipment.", "example": 42 }, "warehouse_id": { "type": "integer", "description": "The warehouse for the outbound shipment.", "example": 5 } }, "required": [ "id", "merchant_id", "warehouse_id" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "outbound_shipment.cancellation_requested": { "post": { "summary": "outbound_shipment.cancellation_requested webhook", "description": "This webhook is sent to subscribed endpoints when the outbound_shipment.cancellation_requested event occurs.", "operationId": "webhook-outbound-shipment-cancellation-requested", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "outbound_shipment.cancellation_requested", "description": "Structured CloudEvent for the outbound_shipment.cancellation_requested webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "outbound_shipment.cancellation_requested" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the outbound shipment.", "example": 7001 }, "merchant_id": { "type": "integer", "description": "The merchant that owns the outbound shipment.", "example": 42 }, "warehouse_id": { "type": "integer", "description": "The warehouse for the outbound shipment.", "example": 5 } }, "required": [ "id", "merchant_id", "warehouse_id" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "outbound_shipment.cancellation_withdrawn": { "post": { "summary": "outbound_shipment.cancellation_withdrawn webhook", "description": "This webhook is sent to subscribed endpoints when the outbound_shipment.cancellation_withdrawn event occurs.", "operationId": "webhook-outbound-shipment-cancellation-withdrawn", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "outbound_shipment.cancellation_withdrawn", "description": "Structured CloudEvent for the outbound_shipment.cancellation_withdrawn webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "outbound_shipment.cancellation_withdrawn" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the outbound shipment.", "example": 7001 }, "merchant_id": { "type": "integer", "description": "The merchant that owns the outbound shipment.", "example": 42 }, "warehouse_id": { "type": "integer", "description": "The warehouse for the outbound shipment.", "example": 5 } }, "required": [ "id", "merchant_id", "warehouse_id" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "outbound_shipment.closed": { "post": { "summary": "outbound_shipment.closed webhook", "description": "This webhook is sent to subscribed endpoints when the outbound_shipment.closed event occurs.", "operationId": "webhook-outbound-shipment-closed", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "outbound_shipment.closed", "description": "Structured CloudEvent for the outbound_shipment.closed webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "outbound_shipment.closed" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the outbound shipment.", "example": 7001 }, "merchant_id": { "type": "integer", "description": "The merchant that owns the outbound shipment.", "example": 42 }, "warehouse_id": { "type": "integer", "description": "The warehouse for the outbound shipment.", "example": 5 }, "previous_status": { "type": "string", "description": "The outbound shipment status before this event.", "example": "open" } }, "required": [ "id", "merchant_id", "warehouse_id", "previous_status" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "outbound_shipment.created": { "post": { "summary": "outbound_shipment.created webhook", "description": "This webhook is sent to subscribed endpoints when the outbound_shipment.created event occurs.", "operationId": "webhook-outbound-shipment-created", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "outbound_shipment.created", "description": "Structured CloudEvent for the outbound_shipment.created webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "outbound_shipment.created" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the outbound shipment.", "example": 7001 }, "merchant_id": { "type": "integer", "description": "The merchant that owns the outbound shipment.", "example": 42 }, "warehouse_id": { "type": "integer", "description": "The warehouse for the outbound shipment.", "example": 5 } }, "required": [ "id", "merchant_id", "warehouse_id" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "outbound_shipment.items_updated": { "post": { "summary": "outbound_shipment.items_updated webhook", "description": "This webhook is sent to subscribed endpoints when the outbound_shipment.items_updated event occurs.", "operationId": "webhook-outbound-shipment-items-updated", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "outbound_shipment.items_updated", "description": "Structured CloudEvent for the outbound_shipment.items_updated webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "outbound_shipment.items_updated" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the outbound shipment.", "example": 2001 }, "merchant_id": { "type": "integer", "description": "The merchant that owns the outbound shipment.", "example": 42 }, "warehouse_id": { "type": "integer", "description": "The warehouse fulfilling the outbound shipment.", "example": 5 }, "outbound_items": { "type": "array", "description": "Item lines for the outbound shipment.", "items": { "type": "object" }, "example": [] } }, "required": [ "id", "merchant_id", "warehouse_id", "outbound_items" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "outbound_shipment.notes_updated": { "post": { "summary": "outbound_shipment.notes_updated webhook", "description": "This webhook is sent to subscribed endpoints when the outbound_shipment.notes_updated event occurs.", "operationId": "webhook-outbound-shipment-notes-updated", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "outbound_shipment.notes_updated", "description": "Structured CloudEvent for the outbound_shipment.notes_updated webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "outbound_shipment.notes_updated" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the outbound shipment.", "example": 7001 }, "merchant_id": { "type": "integer", "description": "The merchant that owns the outbound shipment.", "example": 42 }, "warehouse_id": { "type": "integer", "description": "The warehouse for the outbound shipment.", "example": 5 } }, "required": [ "id", "merchant_id", "warehouse_id" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "outbound_shipment.shipped": { "post": { "summary": "outbound_shipment.shipped webhook", "description": "This webhook is sent to subscribed endpoints when the outbound_shipment.shipped event occurs.", "operationId": "webhook-outbound-shipment-shipped", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "outbound_shipment.shipped", "description": "Structured CloudEvent for the outbound_shipment.shipped webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "outbound_shipment.shipped" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the outbound shipment.", "example": 7001 }, "merchant_id": { "type": "integer", "description": "The merchant that owns the outbound shipment.", "example": 42 }, "warehouse_id": { "type": "integer", "description": "The warehouse for the outbound shipment.", "example": 5 }, "previous_status": { "type": "string", "description": "The outbound shipment status before this event.", "example": "open" } }, "required": [ "id", "merchant_id", "warehouse_id", "previous_status" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "outbound_shipment.status_changed": { "post": { "summary": "outbound_shipment.status_changed webhook", "description": "This webhook is sent to subscribed endpoints when the outbound_shipment.status_changed event occurs.", "operationId": "webhook-outbound-shipment-status-changed", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "outbound_shipment.status_changed", "description": "Structured CloudEvent for the outbound_shipment.status_changed webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "outbound_shipment.status_changed" ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique integer identifier of the outbound shipment.", "example": 7001 }, "merchant_id": { "type": "integer", "description": "The merchant that owns the outbound shipment.", "example": 42 }, "warehouse_id": { "type": "integer", "description": "The warehouse for the outbound shipment.", "example": 5 }, "previous_status": { "type": "string", "description": "The outbound shipment status before this event.", "example": "open" } }, "required": [ "id", "merchant_id", "warehouse_id", "previous_status" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "stripe_merchant_customer.payment_method_added": { "post": { "summary": "stripe_merchant_customer.payment_method_added webhook", "description": "This webhook is sent to subscribed endpoints when the stripe_merchant_customer.payment_method_added event occurs.", "operationId": "webhook-stripe-merchant-customer-payment-method-added", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "stripe_merchant_customer.payment_method_added", "description": "Structured CloudEvent for the stripe_merchant_customer.payment_method_added webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "stripe_merchant_customer.payment_method_added" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The event or Stripe customer identifier associated with the payment method addition.", "example": "cus_123" }, "merchant_id": { "type": "integer", "description": "The merchant that owns the Stripe merchant customer.", "example": 42 }, "payment_method_id": { "type": "string", "description": "The Stripe payment method identifier.", "example": "pm_123" } }, "required": [ "id", "merchant_id", "payment_method_id" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } }, "transportation_tracking.data_updated": { "post": { "summary": "transportation_tracking.data_updated webhook", "description": "This webhook is sent to subscribed endpoints when the transportation_tracking.data_updated event occurs.", "operationId": "webhook-transportation-tracking-data-updated", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/cloudevents+json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "transportation_tracking.data_updated", "description": "Structured CloudEvent for the transportation_tracking.data_updated webhook.", "allOf": [ { "type": "object", "properties": { "specversion": { "enum": [ "1.0" ] }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "datacontenttype": { "enum": [ "application/json" ] }, "time": { "type": "string", "format": "date-time" }, "data": { "type": "object" }, "correlationid": { "type": "string", "minLength": 1, "description": "Identifier shared by CloudEvents produced from the same dispatch call." } }, "required": [ "specversion", "id", "source", "type", "datacontenttype", "time", "data", "correlationid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "enum": [ "transportation_tracking.data_updated" ] }, "data": { "type": "object", "properties": { "status": { "type": "string", "description": "The current tracking status.", "example": "transit" }, "number": { "type": "string", "description": "The carrier tracking number.", "example": "1Z999AA10123456784" }, "carrier": { "type": "string", "description": "The carrier identifier.", "example": "ups" } }, "required": [ "status", "number", "carrier" ], "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Return a 2xx response to indicate that the webhook was received successfully." } } } } }, "tags": [ { "name": "Channels", "description": "Viewing and managing channels and listings" }, { "name": "Billing", "description": "Viewing and managing charges and invoices" }, { "name": "Products", "description": "Viewing product details. Stock quantities are served separately." }, { "name": "Suppliers", "description": "Viewing and managing suppliers, their catalogue items, cost tiers and identifiers" }, { "name": "Sourcing", "description": "Reviewing and deciding matches between supplier items and Amazon catalog items" }, { "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": "Service Providers", "description": "Viewing the service providers a merchant is connected to" }, { "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" }, { "name": "Workflows", "description": "Viewing and dispatching background workflows" }, { "name": "Webhooks", "description": "Webhook events sent to subscribed endpoints" }, { "name": "Sender Domains", "description": "Registering and verifying the domain a service provider sends authenticated mail from" } ], "components": { "schemas": { "NullableMoney": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "NullableMoney", "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?[0-9]+\\.[0-9]{4}$" }, "currency": { "type": "string" } }, "additionalProperties": false, "required": [ "amount", "currency" ] } ] }, "Unauthorized": { "description": "Unauthenticated — no valid API token was provided" }, "Forbidden": { "description": "Forbidden — you do not have permission to access this resource" }, "UnprocessableEntity": { "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" ] } } } }, "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 }, "invoice_id": { "type": [ "number", "null" ], "description": "The invoice id the charge is attached to if any", "example": 155 }, "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" ] }, "NotFound": { "description": "Not Found — the requested resource does not exist" }, "Page": { "type": "integer", "description": "The page number to retrieve (1-indexed)", "example": 1 }, "PerPage": { "type": "integer", "description": "The number of items per page", "example": 15 }, "PaginatedResponse": { "type": "object", "description": "A paginated list of items using the 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" } } }, "required": [ "data", "total", "current_page", "last_page", "per_page", "from", "to" ] }, "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" ] }, "CatalogItemPriceAnalytics": { "type": "object", "properties": { "start": { "type": "string", "format": "date", "description": "The requested start, inclusive." }, "end": { "type": "string", "format": "date", "description": "The requested end, exclusive." }, "granularity": { "type": "string", "enum": [ "day", "week", "month" ] }, "timezone": { "type": "string", "enum": [ "UTC" ] }, "series": { "type": "array", "description": "One series per currency observed in the range, ordered by currency code. Empty when nothing was observed. Currencies are never combined.", "items": { "type": "object", "properties": { "currency": { "type": "string", "description": "ISO 4217 currency code of every price in the series.", "example": "USD" }, "buckets": { "type": "array", "description": "Ascending, contiguous buckets covering the whole requested range.", "items": { "type": "object", "description": "Landed-price summary of one UTC calendar bucket. Edge buckets are clipped to the requested range. A bucket with no observations has null prices and zero counts. The bucket containing the current UTC day may still gain observations.", "properties": { "start": { "type": "string", "format": "date", "description": "First UTC day of the bucket, inclusive." }, "end": { "type": "string", "format": "date", "description": "UTC day after the last day of the bucket, exclusive." }, "lowest_landed_price": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Lowest observed item price plus shipping in the bucket, serialized to four decimal places." }, "highest_landed_price": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Highest observed item price plus shipping in the bucket, serialized to four decimal places." }, "average_landed_price": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+\\.[0-9]{4}$", "description": "Sum of every observed landed price in the bucket divided by observation_count, rounded half-up once to four decimal places. Duplicate observations count; it is not time-weighted." }, "observation_count": { "type": "integer", "minimum": 0, "description": "Number of price observations in the bucket. It counts observations, not time coverage." }, "observed_days": { "type": "integer", "minimum": 0, "description": "Number of UTC days in the bucket with at least one observation in this currency." } }, "required": [ "start", "end", "lowest_landed_price", "highest_landed_price", "average_landed_price", "observation_count", "observed_days" ] } } }, "required": [ "currency", "buckets" ] } } }, "required": [ "start", "end", "granularity", "timezone", "series" ] }, "Channel": { "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", "enum": [ "amazon", "custom", "ebay", "walmart", "woo_commerce" ], "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. Not returned by the custom-channel create endpoint." }, "connection_status": { "type": "string", "description": "The current connection status of the channel. `active` means the channel is connected and enabled; `unauthorized` means it is disconnected or awaiting (re-)authorization.", "enum": [ "active", "unauthorized" ], "example": "active" }, "country_id": { "type": [ "integer", "string", "null" ], "description": "The country ID associated with the channel, if any. Amazon-specific; not returned by the custom-channel create endpoint." }, "marketplace": { "type": [ "string", "null" ], "description": "The Walmart marketplace the channel connects to. Walmart-specific; only returned by the create-walmart-channel endpoint.", "enum": [ "us", "ca", "mx", null ], "example": "us" }, "team_id": { "type": "integer", "description": "Alias for merchant_id" }, "created_at": { "type": "string", "format": "date-time", "description": "When the channel was created. Returned when fetching a single channel; omitted from the list-channels response.", "example": "2026-06-16T12:00:00.000000+00:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the channel was last updated. Returned when fetching a single channel; omitted from the list-channels response.", "example": "2026-06-16T12:00:00.000000+00:00" } }, "additionalProperties": true, "required": [ "id", "merchant_id", "team_id", "type", "nickname", "connection_status" ] }, "Listing": { "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. For Amazon listings whose title equals their SKU, the linked catalog item's title." }, "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. Deprecated for Amazon listings: read amazon.catalog_item. For Amazon listings, derived from the linked Amazon catalog item's package dimensions, falling back to its item dimensions; null when unlinked" }, "width_mm": { "type": [ "integer", "null" ], "description": "The width of the item in millimetres. Deprecated for Amazon listings: read amazon.catalog_item. For Amazon listings, derived from the linked Amazon catalog item's package dimensions, falling back to its item dimensions; null when unlinked" }, "height_mm": { "type": [ "integer", "null" ], "description": "The height of the item in millimetres. Deprecated for Amazon listings: read amazon.catalog_item. For Amazon listings, derived from the linked Amazon catalog item's package dimensions, falling back to its item dimensions; null when unlinked" }, "weight_gm": { "type": [ "integer", "null" ], "description": "The weight of the item in grams. Deprecated for Amazon listings: read amazon.catalog_item. For Amazon listings, derived from the linked Amazon catalog item's package dimensions, falling back to its item dimensions; null when unlinked" }, "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. Deprecated for Amazon listings: read amazon.catalog_item. For Amazon listings, ['hazmat'] when the linked Amazon catalog item is marked hazmat, otherwise []; [] when unlinked", "items": {} }, "identifiers": { "type": "array", "description": "The identifiers associated with this listing. Deprecated for Amazon listings: read amazon.catalog_item. For Amazon listings, derived from the listing's FNSKU and the linked Amazon catalog item's ASIN and associated identifiers; id is null for these derived entries", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "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. Deprecated for Amazon listings: read amazon.catalog_item. For Amazon listings, one entry derived from the linked Amazon catalog item's main and thumbnail images when both are present, otherwise []; id is null for these derived entries", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "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. Deprecated for Amazon listings: read amazon.catalog_item. For Amazon listings, the linked Amazon catalog item's last-updated date; null when unlinked or when the catalog item has not yet synced a snapshot" }, "channel_type": { "type": "string", "description": "The type of the channel this listing belongs to", "example": "amazon" }, "amazon": { "type": [ "object", "null" ], "description": "Amazon-specific facts for this listing. Present when channel_type is 'amazon', null otherwise", "properties": { "fnsku": { "type": [ "string", "null" ], "description": "The listing's current FNSKU" }, "catalog_item": { "type": [ "object", "null" ], "description": "The shared Amazon catalog item this listing is linked to", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "The Amazon catalog item's uuid, usable with the Amazon catalog item prices endpoint", "example": "019b2286-9fee-8019-9f64-154824d3aa4d" }, "marketplace_id": { "type": "string", "example": "ATVPDKIKX0DER" }, "asin": { "type": "string", "example": "B01234567" }, "title": { "type": [ "string", "null" ], "description": "The catalog item's title" }, "associated_identifiers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "EAN" }, "identifier": { "type": "string", "example": "6619524668697" } }, "additionalProperties": false, "required": [ "type", "identifier" ] } }, "main_image_url": { "type": [ "string", "null" ] }, "thumbnail_image_url": { "type": [ "string", "null" ] }, "item_dimensions": { "type": "object", "properties": { "length_mm": { "type": [ "integer", "null" ] }, "width_mm": { "type": [ "integer", "null" ] }, "height_mm": { "type": [ "integer", "null" ] }, "weight_gm": { "type": [ "integer", "null" ] } }, "additionalProperties": false, "required": [ "length_mm", "width_mm", "height_mm", "weight_gm" ] }, "package_dimensions": { "type": "object", "properties": { "length_mm": { "type": [ "integer", "null" ] }, "width_mm": { "type": [ "integer", "null" ] }, "height_mm": { "type": [ "integer", "null" ] }, "weight_gm": { "type": [ "integer", "null" ] } }, "additionalProperties": false, "required": [ "length_mm", "width_mm", "height_mm", "weight_gm" ] }, "is_hazmat": { "type": "boolean" }, "updated_at": { "type": "string", "example": "2024-01-01T00:00:00Z" } }, "additionalProperties": false, "required": [ "uuid", "marketplace_id", "asin", "title", "associated_identifiers", "main_image_url", "thumbnail_image_url", "item_dimensions", "package_dimensions", "is_hazmat", "updated_at" ] } }, "additionalProperties": false, "required": [ "fnsku", "catalog_item" ] }, "walmart": { "type": [ "object", "null" ], "description": "Walmart-specific facts for this listing. Present when channel_type is 'walmart', null otherwise", "properties": { "wpid": { "type": [ "string", "null" ], "description": "The listing's current WPID" }, "catalog_item": { "type": [ "object", "null" ], "description": "The shared Walmart catalog item this listing is linked to", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "The Walmart catalog item's uuid, usable with the Walmart catalog item prices endpoint", "example": "019b2286-9fee-80ea-9f64-154824d3aa4d" }, "marketplace": { "type": "string", "example": "us" }, "gtin": { "type": "string", "example": "00012345678905" }, "item_id": { "type": [ "string", "null" ] }, "associated_identifiers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "UPC" }, "identifier": { "type": "string", "example": "012345678905" } }, "additionalProperties": false, "required": [ "type", "identifier" ] } }, "updated_at": { "type": "string", "example": "2024-01-01T00:00:00Z" } }, "additionalProperties": false, "required": [ "uuid", "marketplace", "gtin", "item_id", "associated_identifiers", "updated_at" ] }, "live_item": { "type": [ "object", "null" ], "description": "The item as Walmart currently lists it under the listing's SKU. Only returned when showing a single listing; null when Walmart has no item for the SKU or the channel is not connected", "properties": { "product_type": { "type": [ "string", "null" ], "example": "T-Shirts" }, "condition": { "type": [ "string", "null" ], "example": "New" }, "published_status": { "type": [ "string", "null" ], "example": "PUBLISHED" }, "lifecycle_status": { "type": [ "string", "null" ], "example": "ACTIVE" } }, "additionalProperties": false, "required": [ "product_type", "condition", "published_status", "lifecycle_status" ] } }, "additionalProperties": false, "required": [ "wpid", "catalog_item" ] } }, "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", "channel_type", "amazon", "walmart" ] }, "WalmartFeed": { "type": "object", "description": "A feed submitted to Walmart for a channel, and how far Walmart has got with it", "properties": { "uuid": { "type": "string", "format": "uuid", "example": "019b2286-9fee-71de-9f64-154824d3aa4d" }, "feed_type": { "type": "string", "description": "The Walmart feed type", "enum": [ "OMNI_WFS", "MP_ITEM_MATCH", "MP_MAINTENANCE", "PRICE_AND_PROMOTION" ], "example": "MP_ITEM_MATCH" }, "status": { "type": "string", "description": "`requested` until it reaches Walmart, `awaiting_result` while Walmart processes it, then `processed` or `failed`. A processed feed can still contain items Walmart rejected; see `items_failed` and `items`.", "enum": [ "requested", "awaiting_result", "processed", "failed" ], "example": "processed" }, "walmart_feed_id": { "type": [ "string", "null" ], "description": "Walmart's id for the feed, once submitted", "example": "F129C19240844B97A3C6AD8F1A2C4997@AU8BAQA" }, "items_received": { "type": [ "integer", "null" ], "example": 1 }, "items_succeeded": { "type": [ "integer", "null" ], "example": 1 }, "items_failed": { "type": [ "integer", "null" ], "example": 0 }, "items_processing": { "type": [ "integer", "null" ], "example": 0 }, "errors": { "type": "array", "description": "Why the feed itself failed. Empty unless `status` is `failed`.", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the feed reached Walmart" }, "processed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When Walmart finished processing the feed" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the feed failed" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "feed_type", "status", "walmart_feed_id", "items_received", "items_succeeded", "items_failed", "items_processing", "errors", "submitted_at", "processed_at", "failed_at", "created_at" ] }, "WalmartListingInventoryLevel": { "type": "object", "description": "The last Walmart inventory levels stored for one listing of the channel. Every listing of the channel has an entry, including listings with no stored level. WFS and ship-node levels come from separate Walmart reports with their own `synced_at`; they may describe the same units, so they must not be added together as separate stock. A stored level is the last one Walmart reported, kept until a later sync replaces it; it is not a guarantee of current stock, and listings Walmart has not reported have no level rather than zero.", "additionalProperties": false, "properties": { "listing_id": { "type": "integer", "description": "The ID of the listing", "example": 21 }, "sku": { "type": "string", "description": "The listing's SKU", "example": "SD-AB-12345" }, "wfs": { "type": [ "object", "null" ], "description": "The listing's Walmart Fulfillment Services level, or null when no WFS level has been stored for it. Null is not zero stock.", "additionalProperties": false, "properties": { "available_units": { "type": [ "integer", "null" ], "description": "Walmart's WFS `availableUnits`; null when Walmart did not report it", "example": 120 }, "reserved_units": { "type": [ "integer", "null" ], "description": "Walmart's WFS `reservedUnits`; null when Walmart did not report it", "example": 4 }, "inbound_units": { "type": [ "integer", "null" ], "description": "Walmart's WFS `inboundUnits`; null when Walmart did not report it", "example": 48 }, "on_hand_units": { "type": [ "integer", "null" ], "description": "Walmart's WFS `onhandUnits`; null when Walmart did not report it", "example": 130 }, "unavailable_units": { "type": [ "integer", "null" ], "description": "Walmart's WFS `unavailableUnits` (`inventoryReviewUnits` plus `inventoryMovementUnits`); null unless Walmart reported both", "example": 6 }, "stock_status": { "type": [ "string", "null" ], "description": "Walmart's WFS `stockStatus`, as Walmart sent it; null when Walmart did not report it", "example": "IN_STOCK" }, "synced_at": { "type": "string", "format": "date-time", "description": "When the Walmart request that returned this level was made. The level is only as current as this time; an old value means later syncs have not replaced it.", "example": "2026-10-07T04:05:12Z" } }, "required": [ "available_units", "reserved_units", "inbound_units", "on_hand_units", "unavailable_units", "stock_status", "synced_at" ] }, "ship_nodes": { "type": "array", "description": "The listing's level at each Walmart ship node, ordered by `ship_node`; empty when no ship-node level has been stored for it. Each node has its own `synced_at`.", "items": { "type": "object", "additionalProperties": false, "properties": { "ship_node": { "type": "string", "description": "The Walmart ship node ID, exactly as Walmart sent it", "example": "0701234567" }, "available_to_sell_quantity": { "type": [ "integer", "null" ], "description": "Walmart's `availToSellQty` for this node; null when Walmart did not report it", "example": 15 }, "input_quantity": { "type": [ "integer", "null" ], "description": "Walmart's `inputQty` for this node; null when Walmart did not report it", "example": 18 }, "reserved_quantity": { "type": [ "integer", "null" ], "description": "Walmart's `reservedQty` for this node; null when Walmart did not report it", "example": 3 }, "synced_at": { "type": "string", "format": "date-time", "description": "When the Walmart request that returned this node's level was made", "example": "2026-10-07T04:06:40Z" } }, "required": [ "ship_node", "available_to_sell_quantity", "input_quantity", "reserved_quantity", "synced_at" ] } } }, "required": [ "listing_id", "sku", "wfs", "ship_nodes" ] }, "WfsInboundOrder": { "type": "object", "description": "A Walmart Fulfillment Services (WFS) inbound order: a request to send inventory into Walmart's fulfillment centers", "properties": { "uuid": { "type": "string", "format": "uuid", "example": "019b2c41-7b1c-80ee-9a51-4d2e8f6b1a90" }, "inbound_order_id": { "type": "string", "description": "The seller's id for the inbound order, unique per channel. Walmart knows the order by this id.", "example": "PO-2026-0042" }, "channel_id": { "type": "integer", "description": "The id of the Walmart channel the order belongs to", "example": 1024 }, "merchant_id": { "type": "integer", "description": "The id of the merchant that owns the channel", "example": 1042 }, "status": { "type": "string", "description": "`draft` until Walmart accepts the order, then `submitted`. `rejected` when Walmart refused it (see `errors`); a rejected order can be submitted again. `closed` once every shipment is received, `cancelled` once Walmart cancels it.", "enum": [ "draft", "submitted", "rejected", "closed", "cancelled" ], "example": "submitted" }, "item_count": { "type": "integer", "description": "The number of SKUs on the order", "example": 1 }, "unit_count": { "type": "integer", "description": "The total units across all items", "example": 120 }, "shipment_ids": { "type": "array", "description": "The ids of the shipments Walmart allocated when it accepted the order. Empty until the order is submitted.", "items": { "type": "string" }, "example": [ "SHP-8812" ] }, "errors": { "type": "array", "description": "Why Walmart rejected the order (`code`, `field`, `description`), or the last Walmart API failure (`code`, `message`, `details`). Cleared when Walmart accepts the order. Position-based rejection errors are dropped when an item is added or removed, because the positions no longer match; SKU-named errors stay until Walmart accepts the order.", "items": { "anyOf": [ { "type": "object", "description": "A rejection reason Walmart returned", "properties": { "code": { "type": "string", "example": "ERR_EXT_DATA_0801001" }, "field": { "type": [ "string", "null" ], "description": "Walmart's reference to the field it refused: the SKU, or a position such as `orderItems[0]`, `orderItems[0].productId`, `orderItems[0].sku` (positions index the order's items as submitted); null when Walmart names none", "example": "orderItems[0].productId" }, "description": { "type": "string", "example": "Item quantity is invalid." } }, "required": [ "code", "field", "description" ] }, { "type": "object", "description": "A failure calling the Walmart API", "properties": { "code": { "type": "string", "example": "500" }, "message": { "type": "string", "example": "Walmart is unavailable" }, "details": { "type": "string", "example": "" } }, "required": [ "code", "message", "details" ] } ] } }, "consecutive_failure_count": { "type": "integer", "description": "How many Walmart API calls for this order have failed in a row. Reset by the next success.", "example": 0 }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When Walmart accepted the order" }, "rejected_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When Walmart last rejected the order" }, "cancellation_requested_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When Walmart accepted a request to cancel the order" }, "last_reconciled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the order's shipments were last refreshed from Walmart" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "inbound_order_id", "channel_id", "merchant_id", "status", "item_count", "unit_count", "shipment_ids", "errors", "consecutive_failure_count", "submitted_at", "rejected_at", "cancellation_requested_at", "last_reconciled_at", "created_at", "updated_at" ] }, "WfsAddress": { "type": "object", "description": "A postal address. Every field is present; a field Walmart or the request did not supply is null.", "properties": { "address_line_1": { "type": [ "string", "null" ], "example": "100 Main St" }, "address_line_2": { "type": [ "string", "null" ], "example": null }, "city": { "type": [ "string", "null" ], "example": "Bentonville" }, "state_code": { "type": [ "string", "null" ], "example": "AR" }, "country_code": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code", "example": "US" }, "postal_code": { "type": [ "string", "null" ], "example": "72712" } }, "required": [ "address_line_1", "address_line_2", "city", "state_code", "country_code", "postal_code" ] }, "WfsInboundOrderDetail": { "description": "An inbound order with its items, shipments and timeline", "allOf": [ { "$ref": "#/components/schemas/WfsInboundOrder" }, { "type": "object", "properties": { "return_address": { "$ref": "#/components/schemas/WfsAddress" }, "inventory_transfer_service": { "type": "boolean", "description": "Whether the order uses Walmart's Inventory Transfer Service: sortable items go to one transfer station instead of being split across fulfilment centres. False is self-distribution, Walmart's default.", "example": false }, "items": { "type": "array", "description": "The SKUs on the order", "items": { "type": "object", "properties": { "sku": { "type": "string", "example": "SKU-1" }, "gtin": { "type": "string", "description": "The item's GTIN, as a 14 digit GTIN-14", "example": "00012345678905" }, "item_description": { "type": "string", "example": "Widget" }, "item_qty": { "type": "integer", "description": "The total units of the SKU", "example": 120 }, "vendor_pack_qty": { "type": "integer", "description": "The number of cases. Equals `item_qty` for loose units.", "example": 12 }, "inner_pack_qty": { "type": "integer", "description": "The units per case. 1 for loose units.", "example": 10 }, "expected_delivery_date": { "type": "string", "format": "date", "example": "2026-10-15" }, "item_labeling": { "type": "boolean", "description": "Whether WFS labels the units (the Item Labeling prep service, sent as `addOnServices: [{serviceType: LABEL}]`). False on items drafted before the option existed.", "example": false } }, "required": [ "sku", "gtin", "item_description", "item_qty", "vendor_pack_qty", "inner_pack_qty", "expected_delivery_date", "item_labeling" ] } }, "shipments": { "type": "array", "description": "The shipments Walmart allocated, oldest first. Empty until the order is submitted.", "items": { "type": "object", "description": "A shipment Walmart allocated for an inbound order: the units to send to one fulfillment center", "properties": { "shipment_id": { "type": "string", "description": "Walmart's id for the shipment", "example": "SHP-8812" }, "fc_name": { "type": [ "string", "null" ], "description": "The fulfillment center the shipment goes to", "example": "DFW5" }, "ship_to_address": { "$ref": "#/components/schemas/WfsAddress" }, "status": { "type": "string", "description": "`superseded` means Walmart replaced the shipment with another one", "enum": [ "created", "pending_shipment_details", "in_transit", "receiving_in_progress", "closed", "cancelled", "failed", "superseded" ], "example": "pending_shipment_details" }, "expected_delivery_date": { "type": [ "string", "null" ], "format": "date", "example": "2026-10-15" }, "updated_expected_delivery_date": { "type": [ "string", "null" ], "format": "date", "description": "The delivery date Walmart revised the shipment to, if any" }, "actual_delivery_date": { "type": [ "string", "null" ], "format": "date" }, "requested_units": { "type": "integer", "example": 120 }, "received_units": { "type": "integer", "example": 0 }, "damaged_units": { "type": [ "integer", "null" ], "example": 0 }, "carrier_name": { "type": [ "string", "null" ], "description": "The carrier on the submitted tracking", "example": "UPS" }, "tracking_numbers": { "type": "array", "items": { "type": "string" }, "example": [ "1Z999AA10123456784" ] }, "allocated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When Walmart allocated the shipment" }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "example": "SKU-1" }, "gtin": { "type": [ "string", "null" ], "description": "Null until the shipment's items are read back from Walmart", "example": "00012345678905" }, "requested_qty": { "type": "integer", "example": 120 }, "received_qty": { "type": "integer", "example": 0 }, "damaged_qty": { "type": "integer", "example": 0 } }, "required": [ "sku", "gtin", "requested_qty", "received_qty", "damaged_qty" ] } }, "carrier_booking": { "type": [ "object", "null" ], "description": "The Walmart preferred carrier booked for the shipment, if any", "properties": { "quote_type": { "type": "string", "enum": [ "Parcel", "LTL", "FTL" ], "example": "LTL" }, "quote_id": { "type": "string", "example": "Q-1" }, "carrier_id": { "type": [ "string", "null" ], "example": "C-9" }, "carrier_name": { "type": [ "string", "null" ], "example": "Acme Freight" }, "currency": { "type": "string", "example": "USD" }, "net_charge_cents": { "type": "integer", "example": 18950 }, "state": { "type": "string", "description": "`cancelled` once the booking is cancelled, `invalidated` once Walmart no longer honours it, `unconfirmed` while Walmart has not confirmed the booking (the next shipment refresh settles it), otherwise `live`", "enum": [ "live", "unconfirmed", "cancelled", "invalidated" ], "example": "live" }, "terms_accepted_at": { "type": "string", "format": "date-time" }, "booked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Null while the booking is `unconfirmed`" }, "cancel_by": { "type": [ "string", "null" ], "format": "date-time", "description": "Informational: the end of Walmart's cancellation window — 24 hours after `terms_accepted_at` (when the charges were accepted) for Parcel, 1 hour for LTL and FTL. Null unless the booking is `live`. A cancellation after it is still sent; Walmart decides.", "example": "2026-09-30T15:02:11Z" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "invalidated_at": { "type": [ "string", "null" ], "format": "date-time" }, "ship_date": { "type": [ "string", "null" ], "format": "date-time" }, "label_generated_at": { "type": [ "string", "null" ], "format": "date-time" }, "pickup": { "type": [ "object", "null" ], "description": "The scheduled carrier pickup, once one is known", "properties": { "confirmation_number": { "type": "string", "example": "PU-77" }, "date": { "type": [ "string", "null" ], "format": "date", "example": "2026-10-01" }, "ready_time": { "type": [ "string", "null" ], "example": "09:00" }, "close_time": { "type": [ "string", "null" ], "example": "17:00" }, "status": { "type": [ "string", "null" ], "description": "Walmart's status for the pickup", "example": "SCHEDULED" } }, "required": [ "confirmation_number", "date", "ready_time", "close_time", "status" ] } }, "required": [ "quote_type", "quote_id", "carrier_id", "carrier_name", "currency", "net_charge_cents", "state", "terms_accepted_at", "booked_at", "cancel_by", "cancelled_at", "invalidated_at", "ship_date", "label_generated_at", "pickup" ] } }, "required": [ "shipment_id", "fc_name", "ship_to_address", "status", "expected_delivery_date", "updated_expected_delivery_date", "actual_delivery_date", "requested_units", "received_units", "damaged_units", "carrier_name", "tracking_numbers", "allocated_at", "items", "carrier_booking" ] } }, "timeline": { "type": "array", "description": "What happened to the order, newest first, at most 200 entries", "items": { "type": "object", "properties": { "event_uuid": { "type": "string", "format": "uuid" }, "event_type": { "type": "string", "description": "What happened, e.g. `drafted`, `item_added`, `submitted`, `rejected`, `api_error_occurred`, `api_recovery_succeeded`, `shipment_allocated`, `shipment_status_changed`, `tracking_submitted`, `tracking_rejected`, `shipment_quantities_updated`, `shipment_quantities_rejected`, `cancellation_requested`, `cancellation_rejected`, `carrier_booked`, `inventory_transfer_service_chosen`, `preview_fetched`, `pickup_observed`, `closed` or `cancelled`", "example": "submitted" }, "user_uuid": { "type": [ "string", "null" ], "format": "uuid", "description": "The user who caused it, or null when it came from Walmart or a background job" }, "shipment_id": { "type": [ "string", "null" ], "description": "The shipment it concerns, or null when it concerns the whole order. Entries recorded before shipments were tracked on the timeline are null.", "example": "SHP-8812" }, "details": { "type": [ "object", "null" ], "description": "What the entry recorded, for entry types that carry it. A `preview_fetched` entry carries `item_labeling_skus` and `destinations` (`type`, `walmart_type`, `ship_node`, `fc_name`, `units`, `net_transfer_charge_cents`, `currency`); every other entry is null." }, "occurred_at": { "type": "string", "format": "date-time" } }, "required": [ "event_uuid", "event_type", "user_uuid", "shipment_id", "details", "occurred_at" ] } } }, "required": [ "return_address", "inventory_transfer_service", "items", "shipments", "timeline" ] } ] }, "WfsInboundOrderBusy": { "description": "Conflict — another request or background job is updating this inbound order; retry shortly", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "This inbound order is busy; try again in a moment." } }, "required": [ "message" ] } } } }, "WfsCarrierCommandRefused": { "description": "The request failed validation, the order's or booking's state refused it, or Walmart refused it. A Walmart refusal is still recorded on the order's timeline, and its `message` is Walmart's first error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Pickup date is not available." }, "errors": { "type": "object", "description": "A map of keys to lists of messages. Validation failures are keyed by field; Walmart's errors are under `walmart`, each as `: `. Absent when the order's or booking's state refused the request.", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "walmart": [ "INVALID_REQUEST: Pickup date is not available." ] } } }, "required": [ "message" ] } } } }, "WfsCarrierCommandFailed": { "description": "The call to Walmart failed or its answer could not be read. The order is left as it was; refresh the shipment to learn whether Walmart applied the change. The failure is recorded on the order's timeline as `api_error_occurred`, except on the third consecutive failure, which records nothing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Walmart did not answer, so the result is unknown. Refresh the shipment to see whether Walmart applied the change." }, "errors": { "type": "object", "properties": { "walmart": { "type": "array", "description": "Each error as `: `", "items": { "type": "string" }, "example": [ "504: Gateway Timeout" ] } }, "required": [ "walmart" ] } }, "required": [ "message", "errors" ] } } } }, "WfsRateQuote": { "type": "object", "description": "A rate quote Walmart returned for a shipment.", "properties": { "uuid": { "type": "string", "format": "uuid", "example": "019b2c52-3f10-7c4e-8a1d-2b3c4d5e6f70" }, "quote_type": { "type": "string", "enum": [ "Parcel", "LTL", "FTL" ], "example": "Parcel" }, "quote_id": { "type": "string", "example": "Q-7781" }, "carrier_id": { "type": [ "string", "null" ], "example": "FEDEX" }, "carrier_name": { "type": [ "string", "null" ], "example": "FedEx" }, "currency": { "type": "string", "example": "USD" }, "net_charge_cents": { "type": "integer", "description": "The amount Walmart charges on booking", "example": 1250 }, "total_charge_cents": { "type": "integer", "description": "Walmart's raw total charge: 0 for Parcel and LTL, the price for FTL", "example": 1500 }, "estimated_delivery_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-08T00:00:00Z" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-02T12:00:00Z" }, "quote_status": { "type": "string", "description": "Walmart's status for the quote", "example": "ACTIVE" }, "requested_at": { "type": "string", "format": "date-time", "example": "2026-10-01T12:00:00Z" }, "selected_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the quote was booked" } }, "required": [ "uuid", "quote_type", "quote_id", "carrier_id", "carrier_name", "currency", "net_charge_cents", "total_charge_cents", "estimated_delivery_at", "expires_at", "quote_status", "requested_at", "selected_at" ] }, "FbaTransportV2024Plan": { "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" ] }, "Operation": { "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" ] }, "ShipmentBoxGroup": { "type": "object", "properties": { "id": { "type": "string", "example": "019b2286-9fee-71de-9f64-154824d3aa4d" }, "length_mm": { "type": "integer", "example": 300 }, "width_mm": { "type": "integer", "example": 200 }, "height_mm": { "type": "integer", "example": 100 }, "weight_gm": { "type": "integer", "example": 1000 }, "number_of_boxes": { "type": "integer", "example": 1 }, "box_numbers": { "type": "array", "items": { "type": "integer", "example": 1 } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "plan_item_id": { "type": "string" }, "quantity": { "type": "integer" } }, "required": [ "id", "plan_item_id", "quantity" ] } } }, "required": [ "id", "length_mm", "width_mm", "height_mm", "weight_gm", "number_of_boxes", "box_numbers", "items" ] }, "BoxGroupItem": { "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" ] }, "InventoryItem": { "$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)" }, "fnskus": { "type": "array", "description": "FNSKU identifier values (present when identifiers are loaded)", "items": { "type": "string" }, "example": [ "X00ABC1234", "X00DEF5678" ] }, "fnsku": { "type": "string", "description": "The first FNSKU identifier value for backwards compatibility (present when identifiers are loaded)", "example": "X00ABC1234" }, "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" ] }, "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 }, "uuid": { "type": "string", "description": "The UUID of the merchant", "example": "550e8400-e29b-41d4-a716-446655440000" }, "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", "uuid", "name", "photoUrl", "enabled", "isOrdersEnabled", "isAmazonShipmentsEnabled" ] }, "SenderDomain": { "type": "object", "description": "A domain a service provider has registered for sending authenticated mail", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique UUID identifier for the sender domain", "example": "550e8400-e29b-41d4-a716-446655440000" }, "domain": { "type": "string", "description": "The registered sending domain, which signs outbound mail", "example": "mg.example.com" }, "from_email": { "type": "string", "format": "email", "description": "The address notifications are sent from once the domain is verified", "example": "info@example.com" }, "verification_status": { "type": "string", "description": "Whether the published DNS records have been confirmed. Rechecked automatically in the background; failed is terminal for this registration.", "enum": [ "pending", "verified", "failed" ], "example": "pending" }, "dns_records": { "type": "array", "description": "The DNS records that must be published for the domain to verify", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The DNS record type", "example": "TXT" }, "name": { "type": "string", "description": "The DNS record name", "example": "mg.example.com" }, "value": { "type": "string", "description": "The DNS record value", "example": "v=spf1 include:mailgun.org ~all" }, "valid": { "type": "boolean", "description": "Whether this record has been observed as published", "example": false }, "priority": { "type": "string", "description": "The MX record priority. Only present on MX records.", "example": "10" } }, "required": [ "type", "name", "value", "valid" ] } } }, "required": [ "id", "domain", "from_email", "verification_status", "dns_records" ] }, "Product": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "Product", "type": "object", "description": "Representation of a product. This endpoint returns product details only — stock quantities are served by the stock endpoints.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "The UUID of the product", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the product was created", "example": "2026-01-15T12:00:00.000000Z" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the product was last updated", "example": "2026-01-15T12:00:00.000000Z" }, "merchant_uuid": { "type": "string", "format": "uuid", "description": "The UUID of the merchant that owns this product", "example": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e" }, "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 product", "example": "Blue Widget" }, "dimensions": { "type": "object", "description": "The measurements of the product, always expressed in millimetres on read. All three measurements are null when the product has no dimensions.", "properties": { "length": { "type": [ "integer", "null" ], "description": "The length of the product, in `unit`", "example": 150 }, "width": { "type": [ "integer", "null" ], "description": "The width of the product, in `unit`", "example": 100 }, "height": { "type": [ "integer", "null" ], "description": "The height of the product, in `unit`", "example": 50 }, "unit": { "type": "string", "description": "The unit the measurements are expressed in. Always `mm` on read.", "enum": [ "mm" ], "example": "mm" } }, "additionalProperties": false, "required": [ "length", "width", "height", "unit" ] }, "weight": { "type": "object", "description": "The weight of the product, always expressed in grams on read. The value is null when the product has no weight.", "properties": { "value": { "type": [ "integer", "null" ], "description": "The weight of the product, in `unit`", "example": 500 }, "unit": { "type": "string", "description": "The unit the weight is expressed in. Always `g` on read.", "enum": [ "g" ], "example": "g" } }, "additionalProperties": false, "required": [ "value", "unit" ] }, "are_dimensions_locked": { "type": [ "boolean", "null" ], "description": "Whether the product dimensions are locked and cannot be edited", "example": false }, "is_deleted": { "type": "boolean", "description": "Whether the product has been deleted. Always false on the list endpoint, which excludes deleted products.", "example": false }, "images": { "type": "array", "description": "Images for the product. Only present when expanded, and always present on the detail endpoint.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier of the image" }, "product_uuid": { "type": [ "string", "null" ], "description": "The UUID of the product 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": "Product identifiers. Only present when expanded, and always present on the detail endpoint.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier of this identifier record" }, "product_uuid": { "type": "string", "description": "The UUID of the product 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": "Tags associated with the product. Only present when expanded, and always present on the detail endpoint.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier of the tag" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the tag was created" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the tag was last updated" }, "name": { "type": "string", "description": "The name of the tag" }, "type": { "type": "string", "description": "The type of the tag" }, "colour": { "type": "string", "description": "The colour of the tag" }, "is_available_for_merchants": { "type": "boolean", "description": "Whether merchants can apply this tag" } }, "additionalProperties": false, "required": [ "id", "name", "type", "colour" ] } } }, "additionalProperties": false, "required": [ "uuid", "merchant_uuid", "merchant_sku", "title", "dimensions", "weight", "are_dimensions_locked", "is_deleted" ] }, "DimensionsInput": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "DimensionsInput", "type": [ "object", "null" ], "description": "The measurements of the product, written as a single field. All three measurements and the unit must be sent together; sending `null` clears all three. Each measurement must convert to between 1 and 500000 millimetres, and is rounded to the nearest millimetre when stored.", "properties": { "length": { "type": "number", "description": "The length of the product, expressed in `unit`", "exclusiveMinimum": 0, "example": 150 }, "width": { "type": "number", "description": "The width of the product, expressed in `unit`", "exclusiveMinimum": 0, "example": 100 }, "height": { "type": "number", "description": "The height of the product, expressed in `unit`", "exclusiveMinimum": 0, "example": 50 }, "unit": { "type": "string", "description": "The unit the measurements are expressed in. Any unit of length is accepted, including `mm`, `cm`, `m`, `in`, `ft` and `yd`.", "example": "mm" } }, "additionalProperties": false, "required": [ "length", "width", "height", "unit" ] }, "WeightInput": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "WeightInput", "type": [ "object", "null" ], "description": "The weight of the product, written as a single field. The value and the unit must be sent together; sending `null` clears the weight. The value must convert to between 1 and 500000 grams, and is rounded to the nearest gram when stored.", "properties": { "value": { "type": "number", "description": "The weight of the product, expressed in `unit`", "exclusiveMinimum": 0, "example": 500 }, "unit": { "type": "string", "description": "The unit the weight is expressed in. Any unit of mass is accepted, including `g`, `kg`, `oz`, `lb` and `st`.", "example": "g" } }, "additionalProperties": false, "required": [ "value", "unit" ] }, "InboundShipment": { "$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" }, "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" ] }, "OutboundShipment": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier for the outbound shipment", "example": 1 }, "reference_id": { "type": [ "string", "null" ], "description": "A human-readable reference identifier for the shipment", "example": "OUSH-011524-1001" }, "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" ] }, "AmazonSourcingComposition": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "merchant_uuid": { "type": "string", "format": "uuid" }, "amazon_catalog_item_uuid": { "type": "string", "format": "uuid" }, "components": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "supplier_item_uuid": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "units_per_supplier_unit": { "type": "integer", "minimum": 1, "maximum": 2147483647 } }, "required": [ "uuid", "supplier_item_uuid", "quantity", "units_per_supplier_unit" ], "additionalProperties": false } }, "verification": { "type": "object", "properties": { "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "rejected_at": { "type": [ "string", "null" ], "format": "date-time" }, "decided_by_user_uuid": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "accepted_at", "rejected_at", "decided_by_user_uuid" ], "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "merchant_uuid", "amazon_catalog_item_uuid", "components", "verification", "created_at", "updated_at" ], "additionalProperties": false }, "AmazonCatalogItemMatch": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "AmazonCatalogItemMatch", "type": "object", "description": "A proposed link between one of the merchant's supplier items and an Amazon catalog item, with the merchant's decision on it.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "The UUID of the match", "example": "019b3c4d-5e6f-80ef-9a0b-1c2d3e4f5a6b" }, "merchant_uuid": { "type": "string", "format": "uuid", "description": "The UUID of the merchant that owns the match", "example": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e" }, "method": { "type": "string", "description": "How the match was found. `shared_identifier`: the supplier item and the catalog item carry the same GTIN.", "enum": [ "shared_identifier" ], "example": "shared_identifier" }, "matched_identifier_type": { "type": "string", "description": "The type of the supplier identifier that produced the match, as stored on the supplier item", "example": "EAN" }, "matched_identifier_value": { "type": "string", "description": "The value of the supplier identifier that produced the match, as stored on the supplier item", "example": "0012345678905" }, "status": { "type": "string", "description": "Derived from the decision timestamps: `accepted` when `accepted_at` is set, `rejected` when `rejected_at` is set, otherwise `pending`.", "enum": [ "pending", "accepted", "rejected" ], "example": "accepted" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the match was accepted. Null unless the status is `accepted`.", "example": "2026-04-01T09:34:55.000000Z" }, "rejected_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the match was rejected. Null unless the status is `rejected`.", "example": null }, "decided_by_user_uuid": { "type": [ "string", "null" ], "format": "uuid", "description": "The UUID of the user who accepted or rejected the match. Null while the match is pending.", "example": "5d2e1f0a-b5a9-4d1a-a2d5-d0e0c2b1c3d7" }, "volume": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2147483647, "description": "Optional merchant sales-volume assumption used by the next asynchronous calculation.", "example": 100 }, "cost_override": { "type": [ "object", "null" ], "description": "Optional per-unit supplier-cost override. Null uses the effective highest-MOQ supplier cost at the next calculation.", "properties": { "amount": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{4}$", "example": "8.2500" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "USD" } }, "additionalProperties": false, "required": [ "amount", "currency" ] }, "fees": { "type": "array", "description": "Merchant-entered per-unit fees. Multiple lines of the same kind are allowed.", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shipping", "prep", "other" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "amount": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{4}$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "additionalProperties": false, "required": [ "kind", "label", "amount", "currency" ] } }, "supplier": { "type": "object", "description": "The supplier of the matched supplier item", "properties": { "uuid": { "type": "string", "format": "uuid", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" }, "name": { "type": "string", "example": "Acme Wholesale" } }, "additionalProperties": false, "required": [ "uuid", "name" ] }, "supplier_item": { "type": "object", "description": "The matched supplier item", "properties": { "uuid": { "type": "string", "format": "uuid", "example": "2b6f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d5" }, "sku": { "type": "string", "example": "ACME-WIDGET-001" }, "description": { "type": [ "string", "null" ], "example": "Blue widget, bulk pack of 10" } }, "additionalProperties": false, "required": [ "uuid", "sku", "description" ] }, "amazon_catalog_item": { "type": "object", "description": "The matched Amazon catalog item", "properties": { "uuid": { "type": "string", "format": "uuid", "example": "3c7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d6" }, "asin": { "type": "string", "example": "B000123456" }, "title": { "type": [ "string", "null" ], "description": "Null until the catalog item has been synced from Amazon", "example": "Acme Blue Widget, Pack of 10" }, "marketplace_id": { "type": "string", "example": "ATVPDKIKX0DER" } }, "additionalProperties": false, "required": [ "uuid", "asin", "title", "marketplace_id" ] }, "created_at": { "type": "string", "format": "date-time", "example": "2026-04-01T09:30:00.000000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-04-01T09:34:55.000000Z" } }, "additionalProperties": false, "required": [ "uuid", "merchant_uuid", "method", "matched_identifier_type", "matched_identifier_value", "status", "accepted_at", "rejected_at", "decided_by_user_uuid", "volume", "cost_override", "fees", "supplier", "supplier_item", "amazon_catalog_item", "created_at", "updated_at" ] }, "SupplierItem": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "SupplierItem", "type": "object", "description": "Representation of a supplier item: a catalogue row a supplier sells, with quantity-break costs and typed identifiers.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "The UUID of the supplier item", "example": "2b6f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d5" }, "supplier_uuid": { "type": "string", "format": "uuid", "description": "The UUID of the supplier this item belongs to", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" }, "merchant_uuid": { "type": "string", "format": "uuid", "description": "The UUID of the merchant that owns this supplier item", "example": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e" }, "sku": { "type": "string", "description": "The supplier's own identifier for this item. Unique among the supplier's items that have not been deleted.", "example": "ACME-WIDGET-001" }, "description": { "type": [ "string", "null" ], "description": "A description of the item", "example": "Blue widget, bulk pack of 10" }, "product_uuid": { "type": [ "string", "null" ], "format": "uuid", "description": "The UUID of the product this supplier item is linked to, if any", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" }, "costs": { "type": "array", "description": "Quantity-break cost tiers for this item, sorted by minimum order quantity", "items": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "SupplierItemCost", "type": "object", "description": "A quantity-break cost tier for a supplier item. Price changes are kept as history: updating the cost inserts a new record rather than overwriting the old one, so `current_cost` and `upcoming_cost` are derived from that history rather than being stored directly.", "properties": { "minimum_order_quantity": { "type": "integer", "description": "The minimum order quantity this cost applies to", "minimum": 1, "example": 100 }, "current_cost": { "$ref": "#/components/schemas/SupplierItem/properties/costs/items/definitions/cost", "description": "The cost currently in effect for this tier" }, "upcoming_cost": { "oneOf": [ { "$ref": "#/components/schemas/SupplierItem/properties/costs/items/definitions/cost" }, { "type": "null" } ], "description": "The next cost scheduled to take effect for this tier, or null if none is scheduled" } }, "additionalProperties": false, "required": [ "minimum_order_quantity", "current_cost", "upcoming_cost" ], "definitions": { "cost": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "The UUID of this cost row. Used to delete this specific price point via `DELETE /suppliers/{supplier_uuid}/items/{supplier_item_uuid}/costs/{supplier_item_cost_uuid}`.", "example": "3c7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d6" }, "amount": { "type": "string", "description": "The cost amount, expressed as a decimal string with 4 decimal places", "example": "12.3700" }, "currency": { "type": "string", "description": "The ISO 4217 currency code this cost is denominated in", "example": "USD" }, "effective_at": { "type": "string", "format": "date-time", "description": "The ISO 8601 datetime from which this cost is, or will be, in effect", "example": "2026-04-01T09:34:55.000000Z" } }, "additionalProperties": false, "required": [ "uuid", "amount", "currency", "effective_at" ] } } } }, "identifiers": { "type": "array", "description": "Typed barcode identifiers for this item", "items": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "SupplierItemIdentifier", "type": "object", "description": "A typed barcode identifier for a supplier item.", "properties": { "type": { "type": "string", "description": "The type of identifier", "enum": [ "UPC", "EAN", "GTIN", "ISBN" ], "example": "UPC" }, "value": { "type": "string", "description": "The identifier value. UPC is 12 digits, EAN is 13 digits, GTIN is 8 to 14 digits, and ISBN is 10 or 13 digits, each after stripping hyphens.", "example": "123456789012" } }, "additionalProperties": false, "required": [ "type", "value" ] } }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the supplier item was created", "example": "2026-01-15T12:00:00.000000Z" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the supplier item was last updated", "example": "2026-01-15T12:00:00.000000Z" }, "is_deleted": { "type": "boolean", "description": "Whether the supplier item has been deleted. Always false on the list endpoint, which excludes deleted supplier items.", "example": false } }, "additionalProperties": false, "required": [ "uuid", "supplier_uuid", "merchant_uuid", "sku", "description", "product_uuid", "costs", "identifiers", "is_deleted" ] }, "Supplier": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "Supplier", "type": "object", "description": "Representation of a supplier: a business a merchant buys stock from.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "The UUID of the supplier", "example": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4" }, "merchant_uuid": { "type": "string", "format": "uuid", "description": "The UUID of the merchant that owns this supplier", "example": "9c1f2b3d-4e5a-4b6c-8d7e-0f1a2b3c4d5e" }, "name": { "type": "string", "description": "The name of the supplier", "example": "Acme Wholesale" }, "default_currency": { "type": "string", "description": "The ISO 4217 currency code used to pre-fill new cost tiers for this supplier's items. Each cost tier still stores its own currency.", "example": "USD" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the supplier was created", "example": "2026-01-15T12:00:00.000000Z" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The ISO 8601 datetime when the supplier was last updated", "example": "2026-01-15T12:00:00.000000Z" }, "is_deleted": { "type": "boolean", "description": "Whether the supplier has been deleted. Always false on the list endpoint, which excludes deleted suppliers.", "example": false } }, "additionalProperties": false, "required": [ "uuid", "merchant_uuid", "name", "default_currency", "is_deleted" ] }, "Workflow": { "type": "object", "properties": { "workflow_id": { "type": "string", "example": "FbaTransport_Autoplanner_abc123" }, "run_id": { "type": "string", "example": "run123" }, "start_time": { "type": "string", "example": "2026-05-14T12:00:00Z" }, "type": { "type": "string", "enum": [ "fbaTransport_copyBoxGroupsFromPlanToPlan", "fbaTransport_autoplanner", "fbaTransport_confirmTransportationOptions", "fbaTransport_confirmPlacementOption", "fbaTransport_splitPackingGroupsIntoPlans" ], "example": "fbaTransport_autoplanner" }, "status": { "type": "string", "example": "RUNNING" }, "progress": { "type": "object", "properties": { "current": { "type": "integer", "example": 50 }, "description": { "type": [ "string", "null" ], "example": "Confirming placement" }, "problems": { "type": [ "array", "null" ], "items": { "type": "object", "properties": {} } } }, "required": [ "current", "description", "problems" ] } }, "required": [ "workflow_id", "run_id", "start_time", "type", "status", "progress" ] }, "ListingRestriction": { "type": "object", "properties": { "id": { "type": "string", "example": "019b2286-9fee-71de-9f64-154824d3aa4d" }, "channel_id": { "type": "integer", "example": 1 }, "asin": { "type": "string", "example": "B00ZB18SIF" }, "marketplace_id": { "type": "string", "example": "ATVPDKIKX0DER" }, "condition_type": { "type": "string", "enum": [ "new_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_new" }, "restrictions": { "type": "array", "items": { "type": "object" } } }, "required": [ "id", "channel_id", "asin", "marketplace_id", "condition_type", "restrictions" ] }, "WfsPackageDimensions": { "type": "object", "properties": { "width_in": { "type": "number", "exclusiveMinimum": 0 }, "height_in": { "type": "number", "exclusiveMinimum": 0 }, "depth_in": { "type": "number", "exclusiveMinimum": 0 }, "weight_lb": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "width_in", "height_in", "depth_in", "weight_lb" ] } }, "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": [] } ] }