openapi: 3.1.0 info: title: Magento REST API description: >- The Adobe Commerce (Magento) REST API provides a comprehensive set of endpoints for interacting with all major aspects of an e-commerce store, including catalog management, orders, customers, inventory, shipping, and payments. It supports three authentication mechanisms: OAuth 1.0a for third-party integrations, token-based authentication for mobile apps and administrators, and guest access for select public endpoints. The API follows REST conventions and returns JSON responses, enabling developers to build integrations, automate store operations, and power headless commerce storefronts. All endpoints are versioned under the /V1 prefix and support searchCriteria query parameters for filtering, sorting, and paginating collection responses. version: '2.4' contact: name: Adobe Commerce Developer Support url: https://developer.adobe.com/commerce/webapi/rest/ termsOfService: https://www.adobe.com/legal/terms.html externalDocs: description: Adobe Commerce REST API Documentation url: https://developer.adobe.com/commerce/webapi/rest/ servers: - url: https://{store_domain}/rest/{store_code} description: Production Server variables: store_domain: default: your-store.example.com description: The hostname of your Adobe Commerce store store_code: default: V1 description: >- Store code followed by API version. Use "all" as store code for admin-scope operations, or the specific store view code for store-scoped operations. The V1 version path segment follows. tags: - name: Authentication description: >- Endpoints for obtaining integration tokens for admin and customer users. Token-based authentication issues a Bearer token that must be included in the Authorization header of subsequent requests. - name: Carts description: >- Shopping cart and quote management for admin, customer, and guest users, including item management, coupon codes, shipping estimation, and payment information collection. - name: Categories description: >- Category tree management including creation, retrieval, update, and deletion of catalog categories and their product assignments. - name: Customers description: >- Customer account management including registration, profile updates, address management, authentication, and customer group assignment. - name: Inventory description: >- Multi-source inventory management including sources, stocks, stock-source links, and source item quantity management. - name: Invoices description: >- Invoice management for orders including invoice creation, retrieval, and payment capture operations. - name: Orders description: >- Sales order management including order retrieval, status updates, comment posting, cancellation, and order item management. - name: Products description: >- Catalog product management including creation, retrieval, update, and deletion of simple, configurable, virtual, bundled, and grouped products. Supports product attributes, media, pricing rules, and cross-sell links. - name: Shipments description: >- Shipment management for orders including shipment creation, retrieval, tracking number management, and shipment comments. - name: Stores description: >- Store configuration retrieval including store groups, store views, websites, and configuration settings. - name: Tax description: >- Tax configuration management including tax rates, tax rules, and tax classes used for order tax calculation. security: - bearerAuth: [] paths: /V1/integration/admin/token: post: operationId: createAdminToken summary: Get admin authentication token description: >- Issues a Bearer token for an admin user based on username and password credentials. The returned token must be included as a Bearer token in the Authorization header of all subsequent admin-scoped API requests. Tokens expire after the configured lifetime (default 4 hours). tags: - Authentication security: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdminTokenRequest' responses: '200': description: Authentication token issued successfully content: application/json: schema: type: string description: Bearer token string for use in Authorization header example: "abc123def456ghi789" '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /V1/integration/customer/token: post: operationId: createCustomerToken summary: Get customer authentication token description: >- Issues a Bearer token for a customer user based on email address and password credentials. The returned token must be included as a Bearer token in the Authorization header of subsequent customer-scoped API requests. Tokens expire after the configured lifetime. tags: - Authentication security: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomerTokenRequest' responses: '200': description: Authentication token issued successfully content: application/json: schema: type: string description: Bearer token string for use in Authorization header '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /V1/products: get: operationId: listProducts summary: List products description: >- Returns a paginated list of products matching the provided search criteria. Supports filtering by any product attribute, sorting by multiple fields, and pagination using currentPage and pageSize parameters within the searchCriteria object. Returns both product data and total count for pagination. tags: - Products parameters: - $ref: '#/components/parameters/searchCriteriaFilterGroups' - $ref: '#/components/parameters/searchCriteriaSortOrders' - $ref: '#/components/parameters/searchCriteriaPageSize' - $ref: '#/components/parameters/searchCriteriaCurrentPage' responses: '200': description: Paginated list of products content: application/json: schema: $ref: '#/components/schemas/ProductSearchResults' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' post: operationId: createProduct summary: Create a product description: >- Creates a new catalog product. The product type is determined by the type_id field in the request body. Supported types include simple, configurable, virtual, downloadable, bundle, and grouped. Custom attributes can be included in the custom_attributes array using attribute codes defined in the catalog. tags: - Products requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProductRequest' responses: '200': description: Product created successfully content: application/json: schema: $ref: '#/components/schemas/Product' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /V1/products/{sku}: get: operationId: getProduct summary: Get product by SKU description: >- Retrieves a single product by its SKU identifier. Returns the full product object including all attributes, media gallery entries, tier prices, and extension attributes. SKUs containing forward slashes or other special characters must be URL-encoded. tags: - Products parameters: - $ref: '#/components/parameters/sku' responses: '200': description: Product object content: application/json: schema: $ref: '#/components/schemas/Product' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' put: operationId: updateProduct summary: Update a product description: >- Updates an existing product identified by its SKU. Only the fields included in the request body are updated; omitted fields retain their existing values. Custom attributes included in the custom_attributes array will overwrite existing attribute values. tags: - Products parameters: - $ref: '#/components/parameters/sku' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProductRequest' responses: '200': description: Updated product object content: application/json: schema: $ref: '#/components/schemas/Product' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' delete: operationId: deleteProduct summary: Delete a product description: >- Permanently deletes a product from the catalog by its SKU. This operation cannot be undone. Associated product attributes, media, and tier prices are also removed. Products assigned to categories will be unassigned prior to deletion. tags: - Products parameters: - $ref: '#/components/parameters/sku' responses: '200': description: Product deleted successfully content: application/json: schema: type: boolean '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /V1/categories: get: operationId: listCategories summary: List categories description: >- Returns the full category tree starting from the specified root category. The response is a nested tree structure with each category containing its children. Use the rootCategoryId parameter to start from a specific category node, and the depth parameter to limit tree traversal depth. tags: - Categories parameters: - name: rootCategoryId in: query description: Root category ID to start the tree from. Defaults to the default root category. required: false schema: type: integer - name: depth in: query description: Maximum depth of the category tree to return. required: false schema: type: integer responses: '200': description: Category tree content: application/json: schema: $ref: '#/components/schemas/CategoryTree' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' post: operationId: createCategory summary: Create a category description: >- Creates a new product category. The parent_id field determines where in the category tree the new category is placed. The position field controls sort order among sibling categories. Custom category attributes can be set via the custom_attributes array. tags: - Categories requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CategoryRequest' responses: '200': description: Category created successfully content: application/json: schema: $ref: '#/components/schemas/Category' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /V1/categories/{categoryId}: get: operationId: getCategory summary: Get category by ID description: >- Retrieves a single category by its numeric identifier. Returns the category data including its name, path, parent ID, and custom attributes. Does not include the full subtree; use the list endpoint for tree traversal. tags: - Categories parameters: - $ref: '#/components/parameters/categoryId' responses: '200': description: Category object content: application/json: schema: $ref: '#/components/schemas/Category' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' put: operationId: updateCategory summary: Update a category description: >- Updates an existing category identified by its numeric ID. Fields included in the request body overwrite existing values. Custom attributes in the custom_attributes array replace their corresponding stored values. tags: - Categories parameters: - $ref: '#/components/parameters/categoryId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CategoryRequest' responses: '200': description: Updated category object content: application/json: schema: $ref: '#/components/schemas/Category' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' delete: operationId: deleteCategory summary: Delete a category description: >- Permanently deletes a category by its numeric ID. Products assigned only to the deleted category will not be deleted but may become uncategorized. Child categories of the deleted category are also deleted recursively. tags: - Categories parameters: - $ref: '#/components/parameters/categoryId' responses: '200': description: Category deleted successfully content: application/json: schema: type: boolean '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /V1/customers: post: operationId: createCustomer summary: Create a customer description: >- Creates a new customer account. The email address must be unique within the store. A password can be provided directly or auto-generated and sent to the customer via email. The customer is assigned to a default customer group unless a group_id is specified in the request. tags: - Customers requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomerRequest' responses: '200': description: Customer created successfully content: application/json: schema: $ref: '#/components/schemas/Customer' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /V1/customers/search: get: operationId: searchCustomers summary: Search customers description: >- Returns a paginated list of customers matching the provided search criteria. Supports filtering by any customer attribute including email, firstname, lastname, group_id, and created_at. Results can be sorted and paginated using searchCriteria parameters. tags: - Customers parameters: - $ref: '#/components/parameters/searchCriteriaFilterGroups' - $ref: '#/components/parameters/searchCriteriaSortOrders' - $ref: '#/components/parameters/searchCriteriaPageSize' - $ref: '#/components/parameters/searchCriteriaCurrentPage' responses: '200': description: Paginated list of customers content: application/json: schema: $ref: '#/components/schemas/CustomerSearchResults' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /V1/customers/{customerId}: get: operationId: getCustomer summary: Get customer by ID description: >- Retrieves a single customer account by its numeric ID. Returns the full customer object including contact details, addresses, and group assignment. Admin authentication is required to retrieve any customer account; customer tokens only allow retrieval of the authenticated customer's own account via the /V1/customers/me endpoint. tags: - Customers parameters: - $ref: '#/components/parameters/customerId' responses: '200': description: Customer object content: application/json: schema: $ref: '#/components/schemas/Customer' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' put: operationId: updateCustomer summary: Update a customer description: >- Updates an existing customer account by its numeric ID. Fields included in the request body overwrite existing values. Partial updates are supported; omitted optional fields retain their current values. Admin authentication is required. tags: - Customers parameters: - $ref: '#/components/parameters/customerId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomerRequest' responses: '200': description: Updated customer object content: application/json: schema: $ref: '#/components/schemas/Customer' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' delete: operationId: deleteCustomer summary: Delete a customer description: >- Permanently deletes a customer account by its numeric ID. All associated data including addresses, order history references, and wishlist items are also removed. This operation cannot be undone. Admin authentication is required. tags: - Customers parameters: - $ref: '#/components/parameters/customerId' responses: '200': description: Customer deleted successfully content: application/json: schema: type: boolean '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /V1/orders: get: operationId: listOrders summary: List orders description: >- Returns a paginated list of sales orders matching the provided search criteria. Supports filtering by status, customer_email, created_at, increment_id, and any other order attribute. Results are sortable and paginated. Admin authentication is required. tags: - Orders parameters: - $ref: '#/components/parameters/searchCriteriaFilterGroups' - $ref: '#/components/parameters/searchCriteriaSortOrders' - $ref: '#/components/parameters/searchCriteriaPageSize' - $ref: '#/components/parameters/searchCriteriaCurrentPage' responses: '200': description: Paginated list of orders content: application/json: schema: $ref: '#/components/schemas/OrderSearchResults' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' post: operationId: createOrder summary: Create an order description: >- Creates a new sales order. The order must include at minimum the billing and shipping address, order items with SKU and quantity, and payment method details. Orders created via the API bypass the standard checkout flow and quote conversion process. tags: - Orders requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OrderRequest' responses: '200': description: Order ID of the created order content: application/json: schema: type: integer description: Numeric order entity ID '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /V1/orders/{orderId}: get: operationId: getOrder summary: Get order by ID description: >- Retrieves a single sales order by its numeric entity ID. Returns the full order object including line items, billing and shipping addresses, payment details, status history, and totals breakdown. Admin authentication is required. tags: - Orders parameters: - $ref: '#/components/parameters/orderId' responses: '200': description: Order object content: application/json: schema: $ref: '#/components/schemas/Order' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /V1/orders/{orderId}/cancel: post: operationId: cancelOrder summary: Cancel an order description: >- Cancels an existing order identified by its numeric entity ID. Only orders in cancellable states (such as pending or processing) can be cancelled. Orders that have already been invoiced or shipped cannot be fully cancelled. Admin authentication is required. tags: - Orders parameters: - $ref: '#/components/parameters/orderId' responses: '200': description: Order cancelled successfully content: application/json: schema: type: boolean '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /V1/orders/{orderId}/comments: post: operationId: addOrderComment summary: Add a comment to an order description: >- Adds a status history comment to an order. Comments can be visible to customers or kept internal for admin use only. An optional email notification can be sent to the customer when the comment is added. The order status can optionally be updated along with the comment. tags: - Orders parameters: - $ref: '#/components/parameters/orderId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OrderCommentRequest' responses: '200': description: Comment added successfully content: application/json: schema: type: boolean '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /V1/invoices: get: operationId: listInvoices summary: List invoices description: >- Returns a paginated list of order invoices matching the provided search criteria. Supports filtering by order_id, state, and other invoice attributes. Admin authentication is required. tags: - Invoices parameters: - $ref: '#/components/parameters/searchCriteriaFilterGroups' - $ref: '#/components/parameters/searchCriteriaSortOrders' - $ref: '#/components/parameters/searchCriteriaPageSize' - $ref: '#/components/parameters/searchCriteriaCurrentPage' responses: '200': description: Paginated list of invoices content: application/json: schema: $ref: '#/components/schemas/InvoiceSearchResults' '401': $ref: '#/components/responses/Unauthorized' /V1/invoices/{invoiceId}: get: operationId: getInvoice summary: Get invoice by ID description: >- Retrieves a single invoice by its numeric entity ID. Returns the full invoice object including line items, totals, and associated order reference. Admin authentication is required. tags: - Invoices parameters: - $ref: '#/components/parameters/invoiceId' responses: '200': description: Invoice object content: application/json: schema: $ref: '#/components/schemas/Invoice' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /V1/order/{orderId}/invoice: post: operationId: createInvoice summary: Create an invoice for an order description: >- Creates a new invoice for an existing order. The invoice can cover all or a subset of the order items by specifying item quantities in the request body. Setting capture to true will immediately attempt payment capture via the order's payment method if supported. tags: - Invoices parameters: - $ref: '#/components/parameters/orderId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InvoiceRequest' responses: '200': description: Invoice entity ID of the created invoice content: application/json: schema: type: integer '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /V1/shipment: post: operationId: createShipment summary: Create a shipment description: >- Creates a new shipment record for an order. The request must include the order_id and the items being shipped with their quantities. Tracking information such as carrier code, title, and tracking number can be included at creation time. An optional shipment comment can also be provided. tags: - Shipments requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ShipmentRequest' responses: '200': description: Shipment entity ID content: application/json: schema: type: integer '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /V1/shipment/{shipmentId}: get: operationId: getShipment summary: Get shipment by ID description: >- Retrieves a single shipment by its numeric entity ID. Returns the full shipment object including shipment items, tracking information, comments, and the associated order reference. Admin authentication is required. tags: - Shipments parameters: - $ref: '#/components/parameters/shipmentId' responses: '200': description: Shipment object content: application/json: schema: $ref: '#/components/schemas/Shipment' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /V1/carts/mine: post: operationId: createCustomerCart summary: Create a cart for the authenticated customer description: >- Creates a new empty shopping cart (quote) for the currently authenticated customer. Returns the cart ID (quote ID) that is used in subsequent cart operations. A customer can only have one active cart at a time; if an active cart already exists, its ID is returned. tags: - Carts responses: '200': description: Cart ID (quote ID) for the customer cart content: application/json: schema: type: integer '401': $ref: '#/components/responses/Unauthorized' /V1/carts/mine/items: post: operationId: addItemToCart summary: Add item to customer cart description: >- Adds a product to the authenticated customer's active cart. The request must include the quote_id, SKU, and quantity. For configurable products, product_option must be included with the selected option values. Returns the updated cart item object. tags: - Carts requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CartItemRequest' responses: '200': description: Cart item added successfully content: application/json: schema: $ref: '#/components/schemas/CartItem' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /V1/guest-carts: post: operationId: createGuestCart summary: Create a guest cart description: >- Creates a new empty shopping cart for a guest (unauthenticated) shopper. Returns a masked cart ID string that is used in subsequent guest cart operations. No authentication is required for this endpoint. The masked ID is a UUID-like string that does not expose internal database IDs. tags: - Carts security: [] responses: '200': description: Masked cart ID for guest cart operations content: application/json: schema: type: string description: Masked cart ID (UUID format) /V1/inventory/sources: get: operationId: listInventorySources summary: List inventory sources description: >- Returns a paginated list of inventory sources configured in the multi-source inventory system. Sources represent physical or logical locations from which inventory is fulfilled. Supports filtering, sorting, and pagination via searchCriteria parameters. tags: - Inventory parameters: - $ref: '#/components/parameters/searchCriteriaFilterGroups' - $ref: '#/components/parameters/searchCriteriaSortOrders' - $ref: '#/components/parameters/searchCriteriaPageSize' - $ref: '#/components/parameters/searchCriteriaCurrentPage' responses: '200': description: Paginated list of inventory sources content: application/json: schema: $ref: '#/components/schemas/InventorySourceSearchResults' '401': $ref: '#/components/responses/Unauthorized' post: operationId: createInventorySource summary: Create an inventory source description: >- Creates a new inventory source in the multi-source inventory system. A source must have a unique source_code, a name, and can optionally include address information and carrier link configurations for shipping integration. tags: - Inventory requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InventorySourceRequest' responses: '200': description: Inventory source created successfully content: application/json: schema: type: object '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /V1/inventory/sources/{sourceCode}: get: operationId: getInventorySource summary: Get inventory source by code description: >- Retrieves a single inventory source by its unique source code string. Returns the full source configuration including address, carrier links, and enabled status. Admin authentication is required. tags: - Inventory parameters: - $ref: '#/components/parameters/sourceCode' responses: '200': description: Inventory source object content: application/json: schema: $ref: '#/components/schemas/InventorySource' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' put: operationId: updateInventorySource summary: Update an inventory source description: >- Updates an existing inventory source identified by its source code. Fields in the request body overwrite existing values. The source_code itself cannot be changed after creation. tags: - Inventory parameters: - $ref: '#/components/parameters/sourceCode' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InventorySourceRequest' responses: '200': description: Inventory source updated successfully content: application/json: schema: type: object '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /V1/inventory/source-items: get: operationId: listSourceItems summary: List source item quantities description: >- Returns a paginated list of source item records representing product quantities at each inventory source. Supports filtering by sku and source_code. This endpoint is used to read stock levels across all inventory sources. Admin authentication is required. tags: - Inventory parameters: - $ref: '#/components/parameters/searchCriteriaFilterGroups' - $ref: '#/components/parameters/searchCriteriaSortOrders' - $ref: '#/components/parameters/searchCriteriaPageSize' - $ref: '#/components/parameters/searchCriteriaCurrentPage' responses: '200': description: Paginated list of source items content: application/json: schema: $ref: '#/components/schemas/SourceItemSearchResults' '401': $ref: '#/components/responses/Unauthorized' post: operationId: updateSourceItems summary: Update source item quantities description: >- Creates or updates source item quantity records in bulk. Each item in the sourceItems array specifies a sku, source_code, quantity, and status. This is the primary endpoint for synchronizing stock levels from external warehouse management systems or ERPs. tags: - Inventory requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SourceItemUpdateRequest' responses: '200': description: Source items updated successfully content: application/json: schema: type: object '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /V1/taxRates: get: operationId: listTaxRates summary: List tax rates description: >- Returns a paginated list of tax rates configured in the store. Tax rates define the percentage applied to taxable items based on country, region, and postal code matching rules. Admin authentication is required. tags: - Tax parameters: - $ref: '#/components/parameters/searchCriteriaFilterGroups' - $ref: '#/components/parameters/searchCriteriaSortOrders' - $ref: '#/components/parameters/searchCriteriaPageSize' - $ref: '#/components/parameters/searchCriteriaCurrentPage' responses: '200': description: Paginated list of tax rates content: application/json: schema: $ref: '#/components/schemas/TaxRateSearchResults' '401': $ref: '#/components/responses/Unauthorized' /V1/store/storeConfigs: get: operationId: listStoreConfigs summary: List store configurations description: >- Returns configuration data for all store views accessible to the authenticated user. Each store config entry includes the store code, base URLs, locale, timezone, currency codes, and weight unit settings. No authentication is required for this endpoint on most store configurations. tags: - Stores security: [] responses: '200': description: List of store configurations content: application/json: schema: type: array items: $ref: '#/components/schemas/StoreConfig' '401': $ref: '#/components/responses/Unauthorized' components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer token obtained from the /V1/integration/admin/token or /V1/integration/customer/token endpoint. Include in the Authorization header as "Bearer {token}". parameters: sku: name: sku in: path description: The product SKU (Stock Keeping Unit) identifier. URL-encode special characters. required: true schema: type: string categoryId: name: categoryId in: path description: The numeric category entity ID. required: true schema: type: integer customerId: name: customerId in: path description: The numeric customer entity ID. required: true schema: type: integer orderId: name: orderId in: path description: The numeric order entity ID. required: true schema: type: integer invoiceId: name: invoiceId in: path description: The numeric invoice entity ID. required: true schema: type: integer shipmentId: name: shipmentId in: path description: The numeric shipment entity ID. required: true schema: type: integer sourceCode: name: sourceCode in: path description: The unique string code identifier for the inventory source. required: true schema: type: string searchCriteriaFilterGroups: name: searchCriteria[filter_groups][0][filters][0][field] in: query description: >- Field name to filter on. Multiple filter groups and filters can be specified using indexed array notation. Filters within a group are OR'd; filter groups themselves are AND'd. required: false schema: type: string searchCriteriaSortOrders: name: searchCriteria[sortOrders][0][field] in: query description: Field name to sort results by. Direction is set in the corresponding direction parameter. required: false schema: type: string searchCriteriaPageSize: name: searchCriteria[pageSize] in: query description: Number of records to return per page. Default varies by resource. required: false schema: type: integer minimum: 1 maximum: 300 searchCriteriaCurrentPage: name: searchCriteria[currentPage] in: query description: Page number to return. First page is 1. required: false schema: type: integer minimum: 1 responses: BadRequest: description: Bad request — invalid input parameters or request body content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized — missing or invalid authentication token content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Not found — the requested resource does not exist content: application/json: schema: $ref: '#/components/schemas/Error' schemas: Error: type: object description: Standard error response returned for 4xx and 5xx responses. properties: message: type: string description: Human-readable error message. parameters: type: array description: Additional error context parameters. items: type: object AdminTokenRequest: type: object description: Request body for obtaining an admin Bearer token. required: - username - password properties: username: type: string description: Admin user login username. password: type: string description: Admin user password. format: password CustomerTokenRequest: type: object description: Request body for obtaining a customer Bearer token. required: - username - password properties: username: type: string description: Customer email address used as the login username. format: email password: type: string description: Customer account password. format: password CustomAttribute: type: object description: A key-value pair representing a custom EAV attribute on a catalog entity. required: - attribute_code - value properties: attribute_code: type: string description: The unique attribute code identifier. value: description: The attribute value. Can be a string, integer, or array depending on the attribute type. Product: type: object description: A catalog product in Adobe Commerce. properties: id: type: integer description: Numeric product entity ID assigned by Commerce. sku: type: string description: Stock Keeping Unit — the unique product identifier. name: type: string description: Display name of the product. attribute_set_id: type: integer description: ID of the attribute set applied to this product. price: type: number format: float description: Base price of the product. status: type: integer description: Product status. 1 = enabled, 2 = disabled. enum: [1, 2] visibility: type: integer description: >- Catalog visibility. 1 = not visible, 2 = catalog only, 3 = search only, 4 = catalog and search. enum: [1, 2, 3, 4] type_id: type: string description: Product type identifier. enum: [simple, configurable, virtual, downloadable, bundle, grouped] created_at: type: string format: date-time description: ISO 8601 timestamp when the product was created. updated_at: type: string format: date-time description: ISO 8601 timestamp when the product was last updated. weight: type: number format: float description: Product weight used for shipping calculations. extension_attributes: type: object description: Extension attributes providing additional module-specific product data. custom_attributes: type: array description: Array of custom EAV attribute values for this product. items: $ref: '#/components/schemas/CustomAttribute' ProductRequest: type: object description: Request body for creating or updating a catalog product. required: - product properties: product: $ref: '#/components/schemas/Product' saveOptions: type: boolean description: Whether to save custom options alongside the product. ProductSearchResults: type: object description: Paginated search results containing a list of products. properties: items: type: array description: Array of product objects matching the search criteria. items: $ref: '#/components/schemas/Product' search_criteria: type: object description: The search criteria applied to generate these results. total_count: type: integer description: Total number of products matching the search criteria across all pages. Category: type: object description: A product category in the catalog category tree. properties: id: type: integer description: Numeric category entity ID. parent_id: type: integer description: Numeric ID of the parent category. name: type: string description: Display name of the category. is_active: type: boolean description: Whether the category is active and visible in the storefront. position: type: integer description: Sort position among sibling categories. level: type: integer description: Depth level of the category in the tree (root = 1). children: type: string description: Comma-separated list of child category IDs. created_at: type: string format: date-time description: ISO 8601 timestamp when the category was created. updated_at: type: string format: date-time description: ISO 8601 timestamp when the category was last updated. path: type: string description: Path string of category IDs from root to this category, separated by slashes. include_in_menu: type: boolean description: Whether this category appears in the navigation menu. custom_attributes: type: array description: Custom EAV attribute values for this category. items: $ref: '#/components/schemas/CustomAttribute' CategoryTree: allOf: - $ref: '#/components/schemas/Category' - type: object properties: children_data: type: array description: Nested child category objects forming the category tree. items: $ref: '#/components/schemas/CategoryTree' CategoryRequest: type: object description: Request body for creating or updating a category. required: - category properties: category: $ref: '#/components/schemas/Category' Address: type: object description: A postal address used for billing or shipping. properties: firstname: type: string description: First name of the address recipient. lastname: type: string description: Last name of the address recipient. email: type: string format: email description: Email address associated with this address record. street: type: array description: Street address lines. items: type: string city: type: string description: City name. region: type: string description: State or region name. region_code: type: string description: Two-letter state or region code. country_id: type: string description: ISO 3166-1 alpha-2 country code. minLength: 2 maxLength: 2 postcode: type: string description: Postal or ZIP code. telephone: type: string description: Phone number for this address. Customer: type: object description: A registered customer account in Adobe Commerce. properties: id: type: integer description: Numeric customer entity ID. group_id: type: integer description: ID of the customer group this customer belongs to. email: type: string format: email description: Customer email address, used as the login identifier. firstname: type: string description: Customer first name. lastname: type: string description: Customer last name. store_id: type: integer description: ID of the store view where this customer account was created. website_id: type: integer description: ID of the website scope for this customer account. created_at: type: string format: date-time description: ISO 8601 timestamp when the customer account was created. updated_at: type: string format: date-time description: ISO 8601 timestamp when the customer account was last updated. addresses: type: array description: Customer address book entries. items: $ref: '#/components/schemas/Address' custom_attributes: type: array description: Custom EAV attribute values for this customer. items: $ref: '#/components/schemas/CustomAttribute' CustomerRequest: type: object description: Request body for creating or updating a customer account. required: - customer properties: customer: $ref: '#/components/schemas/Customer' password: type: string description: Plain-text password to set on the customer account. If omitted, a password reset email is sent. format: password CustomerSearchResults: type: object description: Paginated search results containing a list of customer accounts. properties: items: type: array description: Array of customer objects matching the search criteria. items: $ref: '#/components/schemas/Customer' search_criteria: type: object description: The search criteria applied. total_count: type: integer description: Total number of matching customers across all pages. OrderItem: type: object description: A line item within a sales order. properties: item_id: type: integer description: Numeric order item entity ID. order_id: type: integer description: Numeric ID of the parent order. sku: type: string description: SKU of the ordered product. name: type: string description: Name of the ordered product at the time of purchase. qty_ordered: type: number description: Quantity ordered. qty_invoiced: type: number description: Quantity that has been invoiced. qty_shipped: type: number description: Quantity that has been shipped. price: type: number description: Unit price of the product. row_total: type: number description: Total price for this line item (price x qty). product_type: type: string description: Product type of the ordered item. Order: type: object description: A sales order in Adobe Commerce. properties: entity_id: type: integer description: Numeric order entity ID. increment_id: type: string description: Human-readable order number (e.g. 000000001). status: type: string description: Current order status code (e.g. pending, processing, complete, closed, canceled). state: type: string description: Internal order state (e.g. new, processing, complete, closed, canceled, holded). customer_id: type: integer description: Numeric customer entity ID. Null for guest orders. customer_email: type: string format: email description: Email address of the customer or guest who placed the order. customer_firstname: type: string description: Customer first name. customer_lastname: type: string description: Customer last name. customer_is_guest: type: boolean description: Whether the order was placed by a guest (unauthenticated) shopper. created_at: type: string format: date-time description: ISO 8601 timestamp when the order was created. updated_at: type: string format: date-time description: ISO 8601 timestamp when the order was last updated. grand_total: type: number description: Order grand total including tax and shipping. subtotal: type: number description: Order subtotal before tax and shipping. tax_amount: type: number description: Total tax amount applied to the order. shipping_amount: type: number description: Shipping amount charged on the order. discount_amount: type: number description: Total discount amount applied to the order. billing_address: $ref: '#/components/schemas/Address' items: type: array description: Line items in the order. items: $ref: '#/components/schemas/OrderItem' OrderRequest: type: object description: Request body for creating a sales order directly via the API. required: - entity properties: entity: $ref: '#/components/schemas/Order' OrderCommentRequest: type: object description: Request body for adding a status history comment to an order. required: - statusHistory properties: statusHistory: type: object description: Status history comment details. properties: comment: type: string description: The comment text to add to the order history. is_customer_notified: type: integer description: Whether to send an email notification to the customer. 1 = yes, 0 = no. enum: [0, 1] is_visible_on_front: type: integer description: Whether the comment is visible to the customer in their account. 1 = yes, 0 = no. enum: [0, 1] status: type: string description: Optional new order status to set along with the comment. OrderSearchResults: type: object description: Paginated search results containing a list of orders. properties: items: type: array description: Array of order objects matching the search criteria. items: $ref: '#/components/schemas/Order' search_criteria: type: object description: The search criteria applied. total_count: type: integer description: Total number of matching orders across all pages. Invoice: type: object description: An invoice record associated with a sales order. properties: entity_id: type: integer description: Numeric invoice entity ID. order_id: type: integer description: Numeric entity ID of the parent order. increment_id: type: string description: Human-readable invoice number. state: type: integer description: Invoice state. 1 = open, 2 = paid, 3 = cancelled. enum: [1, 2, 3] grand_total: type: number description: Invoice grand total. subtotal: type: number description: Invoice subtotal. created_at: type: string format: date-time description: ISO 8601 timestamp when the invoice was created. InvoiceRequest: type: object description: Request body for creating an invoice for an order. properties: capture: type: boolean description: Whether to immediately capture payment when creating the invoice. items: type: array description: Order items and quantities to include in the invoice. Omit to invoice all items. items: type: object properties: order_item_id: type: integer description: Numeric order item entity ID. qty: type: number description: Quantity to invoice for this item. comment: type: object description: Optional comment to attach to the invoice. properties: comment: type: string description: Comment text. is_customer_notified: type: integer description: Whether to email the comment to the customer. enum: [0, 1] InvoiceSearchResults: type: object description: Paginated search results containing a list of invoices. properties: items: type: array items: $ref: '#/components/schemas/Invoice' total_count: type: integer description: Total number of matching invoices. Shipment: type: object description: A shipment record tracking the physical dispatch of order items. properties: entity_id: type: integer description: Numeric shipment entity ID. order_id: type: integer description: Numeric entity ID of the parent order. increment_id: type: string description: Human-readable shipment number. created_at: type: string format: date-time description: ISO 8601 timestamp when the shipment was created. tracks: type: array description: Tracking information for this shipment. items: type: object properties: carrier_code: type: string description: Carrier code (e.g. ups, fedex, usps). title: type: string description: Human-readable carrier name. track_number: type: string description: Tracking number provided by the carrier. ShipmentRequest: type: object description: Request body for creating a shipment record for an order. required: - entity properties: entity: $ref: '#/components/schemas/Shipment' CartItem: type: object description: A product line item in a shopping cart (quote). properties: item_id: type: integer description: Numeric cart item entity ID. sku: type: string description: SKU of the product in the cart. qty: type: number description: Quantity of the product in the cart. name: type: string description: Display name of the product. price: type: number description: Unit price of the product. product_type: type: string description: Product type of the cart item. quote_id: type: string description: The cart (quote) ID this item belongs to. CartItemRequest: type: object description: Request body for adding an item to a shopping cart. required: - cartItem properties: cartItem: $ref: '#/components/schemas/CartItem' InventorySource: type: object description: An inventory source representing a fulfillment location in multi-source inventory. properties: source_code: type: string description: Unique string code identifier for the inventory source. name: type: string description: Human-readable name of the inventory source. enabled: type: boolean description: Whether this source is active and available for inventory assignment. description: type: string description: Optional description of the inventory source. latitude: type: number description: Geographic latitude of the source location. longitude: type: number description: Geographic longitude of the source location. country_id: type: string description: ISO 3166-1 alpha-2 country code of the source address. region: type: string description: State or region name of the source address. city: type: string description: City of the source address. street: type: string description: Street address of the source location. postcode: type: string description: Postal code of the source address. InventorySourceRequest: type: object description: Request body for creating or updating an inventory source. required: - source properties: source: $ref: '#/components/schemas/InventorySource' InventorySourceSearchResults: type: object description: Paginated search results containing a list of inventory sources. properties: items: type: array items: $ref: '#/components/schemas/InventorySource' total_count: type: integer description: Total number of matching inventory sources. SourceItem: type: object description: A source item representing the quantity of a product at a specific inventory source. properties: sku: type: string description: SKU of the product. source_code: type: string description: Code of the inventory source holding this quantity. quantity: type: number description: Available quantity of the product at this source. status: type: integer description: In-stock status. 1 = in stock, 0 = out of stock. enum: [0, 1] SourceItemUpdateRequest: type: object description: Request body for bulk updating source item quantities. required: - sourceItems properties: sourceItems: type: array description: Array of source item quantity records to create or update. items: $ref: '#/components/schemas/SourceItem' SourceItemSearchResults: type: object description: Paginated search results containing a list of source items. properties: items: type: array items: $ref: '#/components/schemas/SourceItem' total_count: type: integer description: Total number of matching source item records. TaxRate: type: object description: A tax rate configuration defining the percentage applied to taxable items. properties: id: type: integer description: Numeric tax rate entity ID. tax_country_id: type: string description: ISO 3166-1 alpha-2 country code this rate applies to. tax_region_id: type: integer description: Numeric region ID this rate applies to. 0 for all regions. tax_postcode: type: string description: Postal code pattern this rate applies to. Use * as a wildcard. code: type: string description: Human-readable tax rate code (e.g. US-CA-*-Rate 1). rate: type: number description: Tax percentage rate (e.g. 8.25 for 8.25%). TaxRateSearchResults: type: object description: Paginated search results containing a list of tax rates. properties: items: type: array items: $ref: '#/components/schemas/TaxRate' total_count: type: integer description: Total number of matching tax rates. StoreConfig: type: object description: Configuration settings for a store view. properties: id: type: integer description: Numeric store view entity ID. code: type: string description: Unique string code identifier for the store view. website_id: type: integer description: ID of the website this store view belongs to. locale: type: string description: Locale code for this store (e.g. en_US, fr_FR). base_currency_code: type: string description: ISO 4217 currency code for the base currency (e.g. USD). default_display_currency_code: type: string description: ISO 4217 currency code for the display currency. timezone: type: string description: Timezone identifier (e.g. America/Chicago). weight_unit: type: string description: Weight unit used for this store (lbs or kgs). enum: [lbs, kgs] base_url: type: string format: uri description: Base URL of the store frontend. base_link_url: type: string format: uri description: Base link URL for the store. base_media_url: type: string format: uri description: Base URL for media assets in this store. secure_base_url: type: string format: uri description: Secure (HTTPS) base URL of the store frontend.