--- updatedAt: 2026-09-21T13:38:31.000Z agentTools: projectIndex: https://docs.staxpayments.com/llms.txt --- # Create a Catalog Item Creates an item to be stored in a merchant's catalog. This endpoint creates an item to be stored in a merchant's catalog. The item uses `is_active`, `is_taxable`, `is_service` or `is_discount` to denote whether the item is actively sold, taxable, a service or a discount, respectively. You can create a product, service or discount item to be added to the catalog. ## Duplicate Item Detection The API prevents duplicate catalog items from being created within the same merchant. A duplicate is identified when all of the following fields match an existing, non-deleted item: | Field | Matching Behavior | | :------------ | :-------------------------------------------------------------------------------- | | `item` (name) | Case-insensitive comparison (e.g., "Widget" and "WIDGET" are considered the same) | | `price` | Exact match | | `is_service` | Exact match (defaults to `false` if omitted) | | `is_discount` | Exact match (defaults to `false` if omitted) | If a duplicate is detected, the API returns a `422` response: ```json { "item": ["This item already exists in your Catalog."] } ``` Items with the same name are allowed when the price or type (`is_service`/`is_discount`) differs. Items that have been deleted (soft-deleted) do not count as duplicates. If the server is unable to process the request due to concurrent duplicate checks, a `429` response is returned: ```json { "error": ["Unable to create this item right now. Please try again."] } ``` ## To create a product item To create a product, `is_discount ` and `is_service` would be set to false for a product. | Variable | Description | | :---------------- | :---------------------------------------------------------------------------------------------------------------------------- | | item | Name of the item. | | price | The price to set for the product or service. | | category | You can choose a category for the item. | | details | Details provide the description of the item. Maximum length is 500 characters (raised from 255 as of the 2026-09-17 release). | | code | This is the internal code for the item. | | in\_stock | The value that is on hand. | | low\_stock\_alert | The value that will issue a low stock alert. | | is\_service | Set to False. | | is\_active | Set to True if this item is available to be used. | | is\_taxable | Sets if the item is taxable. True is taxable, while False would be tax-exempt. | | is\_discount | Set to False. | | is\_discountable | If True, the item price can be affected by a discount. | | files | Add file IDs to be associated with the item. | | thumbnail\_id | Associates a file ID with a thumbnail image of the item. This can help identify the item in the UI. | ## To create a service To create a service, `is_discount ` would be set to False and `is_service` would be set to True for a service. | Variable | Description | | :--------------- | :---------------------------------------------------------------------------------------------------------------------------- | | item | Name of the item. | | price | The price to set for the service. | | category | You can choose a category for the item. | | details | Details provide the description of the item. Maximum length is 500 characters (raised from 255 as of the 2026-09-17 release). | | code | This is the internal code for the item. | | is\_service | Set to true. | | is\_active | Set to True if this item is available to be used. | | is\_taxable | Sets if the item is taxable. True is taxable, while False would be tax-exempt. | | is\_discount | Set to False. | | is\_discountable | If True, the item price can be affected by a discount. | | files | Add file IDs to be associated with the item. | | thumbnail\_id | Associates a file ID with a thumbnail image of the item. This can help identify the item in the UI. | ## To create a discount item To create a discount, `is_discount ` is set to True for a discount. | Variable | Description | | :---------------- | :---------------------------------------------------------------------------------------------------------------------------- | | item | Name of the item. | | price | The amount to be discounted. If `is_percentage` is True, this value is a percentage; otherwise, it is a dollar amount. | | category | You can choose a category for the item. | | details | Details provide the description of the item. Maximum length is 500 characters (raised from 255 as of the 2026-09-17 release). | | code | This is the internal code for the item. | | in\_stock | The number of discounts available. | | low\_stock\_alert | A warning is received when the stock reaches this level. | | is\_active | Set to True if this item is available to be used. | | is\_discount | Set to True to create a discount item. | | is\_percentage | Determines if the price variable is a dollar amount or a percentage. | | files | Add file IDs to be associated with the item. | | thumbnail\_id | Associates a file ID with a thumbnail image of the item. This can help identify the item in the UI. | # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "stax-api", "version": "0.1" }, "servers": [ { "url": "https://apiprod.fattlabs.com/" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "API key for merchant-level operations. Provides access to merchant-specific endpoints including transactions, payments, customer management, and merchant account settings. This key is scoped to a single merchant account and cannot access partner-level functionality." } } }, "security": [ { "ApiKeyAuth": [] } ], "paths": { "/item": { "post": { "summary": "Create a Catalog Item", "description": "Creates an item to be stored in a merchant's catalog.", "operationId": "create-catalog-item", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "item" ], "properties": { "item": { "type": "string" }, "code": { "type": "string", "description": "Internal code for the item." }, "details": { "type": "string", "description": "Provides a description of the item." }, "category": { "type": "string", "description": "Provide a description or category to organize items." }, "price": { "type": "number", "description": "Price of the item.", "format": "float" }, "in_stock": { "type": "integer", "description": "Set exact quantity.", "format": "int32" }, "is_service": { "type": "boolean", "description": "Determine if it is a service or product." }, "is_active": { "type": "boolean", "description": "Sets whether this item is active or inactive." }, "is_taxable": { "type": "boolean", "description": "Sets whether the item is taxable or not." }, "is_discount": { "type": "boolean", "description": "Sets the item to a discount. If true, this will override the is_service variable." }, "user_id": { "type": "string" }, "meta": { "type": "string" }, "thumbnail_id": { "type": "string" }, "files": { "type": "string" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "id": "9cf3bd88-da1b-4f35-a5a1-74153c8e7f28", "user_id": "2d089742-6aca-462d-8db3-c2966e1f9e68", "merchant_id": "a61d78cc-cde9-44ac-8a18-30c39be05879", "thumbnail_id": null, "item": "test item", "code": "aaaa", "category": "essential items", "details": "just a test item", "is_active": true, "is_taxable": false, "is_service": false, "is_discount": false, "price": 7.11, "in_stock": 0, "low_stock_alert": 3, "meta": [], "created_at": "2018-10-02 14:28:50", "updated_at": "2018-10-02 14:28:50", "deleted_at": null, "user": { "id": "2d089742-6aca-462d-8db3-c2966e1f9e68", "system_admin": true, "name": "Morty Junior", "email": "contact@example.com", "email_verification_sent_at": "2018-09-26 18:24:21", "email_verified_at": "2016-05-11 17:13:33", "is_api_key": false, "acknowledgments": { "signedApplication": true, "editedOnboardingInformation": false, "tutorial": true, "godviewWelcome": true }, "created_at": "2016-05-18 14:11:46", "updated_at": "2018-09-26 18:24:21", "deleted_at": null, "gravatar": "//www.gravatar.com/avatar/772cbf95746d7da86789cc3634c46ba8", "team_admin": null, "team_enabled": null, "team_role": null, "merchant_options": [], "is_default": false }, "files": [], "thumbnail": null } } }, "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "9cf3bd88-da1b-4f35-a5a1-74153c8e7f28" }, "user_id": { "type": "string", "example": "2d089742-6aca-462d-8db3-c2966e1f9e68" }, "merchant_id": { "type": "string", "example": "a61d78cc-cde9-44ac-8a18-30c39be05879" }, "thumbnail_id": { "type": "string" }, "item": { "type": "string", "example": "test item" }, "code": { "type": "string", "example": "aaaa" }, "category": { "type": "string", "example": "essential items" }, "details": { "type": "string", "example": "just a test item" }, "is_active": { "type": "boolean", "example": true, "default": true }, "is_taxable": { "type": "boolean", "example": false, "default": true }, "is_service": { "type": "boolean", "example": false, "default": true }, "is_subscription": { "type": "boolean", "example": false, "default": true }, "is_discount": { "type": "boolean", "example": false, "default": true }, "price": { "type": "number", "example": 7.11, "default": 0 }, "in_stock": { "type": "integer", "example": 0, "default": 0 }, "low_stock_alert": { "type": "integer", "example": 3, "default": 0 }, "meta": { "type": "array" }, "created_at": { "type": "string", "example": "2018-10-02 14:28:50" }, "updated_at": { "type": "string", "example": "2018-10-02 14:28:50" }, "deleted_at": {}, "user": { "type": "object", "properties": { "id": { "type": "string", "example": "2d089742-6aca-462d-8db3-c2966e1f9e68" }, "system_admin": { "type": "boolean", "example": true, "default": true }, "name": { "type": "string", "example": "Morty Junior" }, "email": { "type": "string", "example": "contact@example.com" }, "email_verification_sent_at": { "type": "string", "example": "2018-09-26 18:24:21" }, "email_verified_at": { "type": "string", "example": "2016-05-11 17:13:33" }, "is_api_key": { "type": "boolean", "example": false, "default": true }, "acknowledgments": { "type": "object", "properties": { "signedApplication": { "type": "boolean", "example": true, "default": true }, "editedOnboardingInformation": { "type": "boolean", "example": false, "default": true }, "tutorial": { "type": "boolean", "example": true, "default": true }, "godviewWelcome": { "type": "boolean", "example": true, "default": true } } }, "created_at": { "type": "string", "example": "2016-05-18 14:11:46" }, "updated_at": { "type": "string", "example": "2018-09-26 18:24:21" }, "deleted_at": {}, "gravatar": { "type": "string", "example": "//www.gravatar.com/avatar/772cbf95746d7da86789cc3634c46ba8" }, "team_admin": {}, "team_enabled": {}, "team_role": {}, "merchant_options": { "type": "array" }, "is_default": { "type": "boolean", "example": false, "default": true } } }, "files": { "type": "array" }, "thumbnail": {} } } } } }, "422": { "description": "422", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"sort\": [\n \"The selected sort is invalid.\"\n ],\n \"order\": [\n \"The selected order is invalid.\"\n ],\n \"is_active\": [\n \"The is active field must be true or false.\"\n ]\n}" } }, "schema": { "type": "object", "properties": { "sort": { "type": "array", "items": { "type": "string", "example": "The selected sort is invalid." } }, "order": { "type": "array", "items": { "type": "string", "example": "The selected order is invalid." } }, "is_active": { "type": "array", "items": { "type": "string", "example": "The is active field must be true or false." } } } } } } } } } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ```