> ## Documentation Index > Fetch the complete documentation index at: https://vexioncards.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create a product > Creates a **manual catalog entry** at one location. Scope: `products:write`. Entries you create are `source: "api"`. POS-sourced entries cannot be created here - they arrive through the location's POS sync and carry a read-only `pos_ref`. Supply a `sku` so transaction line items resolve to this product - `409 sku_already_exists` when the key is already used at this location. ## What the server owns You supply the catalog data (`location_id`, `name`, `sku`, `category`, `tags`, `price_minor`). Everything else is server-computed and rejected with `422 parameter_unknown` if supplied: - `pos_ref` - owned by the POS sync. If callers could set it, a manual entry could impersonate a till product and corrupt line-item resolution - same protection as `Transaction.source` - `source` - server-stamped `"api"` (provenance is never client-claimed) - `id`, `created_at`, `updated_at` - platform-minted ## OpenAPI ````yaml /openapi.json post /v1/products openapi: 3.1.0 info: title: VEXiON cards Public API description: >- ## Rate limiting Two independent layers, checked in this order: 1. **Per-IP throttle (pre-authentication).** Applied to every `/v1` request BEFORE the API key is checked, keyed on the caller's IP address: - **600 requests/minute** per IP - a flood ceiling, `429 rate_limit_error` / `rate_limited`. - **20 failed authentications per 15 minutes** per IP - a key-guessing ceiling. Only responses that are `401` (missing/invalid/revoked key) count against this ceiling; a `403` from a valid key that simply lacks a scope does not. `429 rate_limit_error` / `too_many_failed_attempts`. Both ceilings send `Retry-After` (seconds). 2. **Per-key, per-bucket limiter (post-authentication).** Documented per endpoint (see each operation's `429` response and the `rate_limit` field on the API Key resource) - e.g. 60/min default, 120/min for transactions, plus the notification-broadcast and lookup-filter buckets described on their own endpoints. ### Rate-limit response headers Every rate-limited response carries the legacy `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` family (the last is an **epoch timestamp**) AND the IETF standards-track headers, side by side: - `RateLimit-Policy: "";q=;w=` - the static policy for the bucket that was hit. - `RateLimit: "";r=;t=` - live state. **`t` is a DURATION (seconds remaining), not the epoch timestamp `X-RateLimit-Reset` carries - the two are never the same value.** version: 1.0.0 servers: - url: https://api.vexioncards.one description: Production - url: https://migration.api.vexioncards.one description: Sandbox security: - apiKey: [] tags: - name: Customers - name: Cards - name: Transactions - name: Notifications - name: Locations - name: Products - name: API keys - name: Organization - name: Webhook endpoints - name: Events - name: Custom fields - name: Team members - name: Icons paths: /v1/products: post: tags: - Products summary: Create a product description: >- Creates a **manual catalog entry** at one location. Scope: `products:write`. Entries you create are `source: "api"`. POS-sourced entries cannot be created here - they arrive through the location's POS sync and carry a read-only `pos_ref`. Supply a `sku` so transaction line items resolve to this product - `409 sku_already_exists` when the key is already used at this location. ## What the server owns You supply the catalog data (`location_id`, `name`, `sku`, `category`, `tags`, `price_minor`). Everything else is server-computed and rejected with `422 parameter_unknown` if supplied: - `pos_ref` - owned by the POS sync. If callers could set it, a manual entry could impersonate a till product and corrupt line-item resolution - same protection as `Transaction.source` - `source` - server-stamped `"api"` (provenance is never client-claimed) - `id`, `created_at`, `updated_at` - platform-minted operationId: createProduct parameters: - name: Idempotency-Key in: header required: true description: >- Required on every mutating POST. 24h byte-replay on the same key + body; `409 idempotency_key_conflict` on body mismatch. See [Idempotency](/api-reference/idempotency). schema: type: string minLength: 8 maxLength: 255 example: 9c1d6b00-2a3f-4f9c-8a6f-2e10b9e34c12 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProductCreateRequest' examples: Drink with SKU: summary: Recommended shape value: location_id: loc_01HW9R4P2ZK7N8MTX1RVLOCS01 name: Flat White sku: FW-12 category: drinks price_minor: 350 Minimal: summary: Name only (no correlation) value: location_id: loc_01HW9R4P2ZK7N8MTX1RVLOCS01 name: Seasonal special Bilingual product: summary: Per-language names (SK/EN border store) value: location_id: loc_01HW9R4P2ZK7N8MTX1RVLOCS01 name: sk: Biela káva en: Flat White sku: FW-12 category: drinks price_minor: 350 responses: '201': description: Product created. content: application/json: schema: $ref: '#/components/schemas/Product' examples: Created: summary: 'source: api, no pos_ref' value: id: prd_01HW9R7T2CD8N8MTX1RVPRDFW1 object: product location_id: loc_01HW9R4P2ZK7N8MTX1RVLOCS01 name: Flat White sku: FW-12 category: drinks tags: - coffee - hot price_minor: 350 source: api pos_ref: null is_active: true created_at: 1750000000 updated_at: 1750000000 '400': description: Malformed request. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing, invalid, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Key lacks the required scope. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Resource not found in your organization. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: SKU collision or idempotency conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SKU already exists: summary: Unique per location value: error: type: invalid_request_error code: sku_already_exists message: >- SKU 'FW-12' is already used by prd_01HW9R7T2CD8N8MTX1RVPRDFW1 at this location. request_id: req_01HW9Q3K2YJZ7M5RX1P8VTBNC4 param: sku '413': description: >- Request body exceeds the 1 MB cap. The body was never parsed, so the request had no effect. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: invalid_request_error code: request_too_large message: The request body exceeds the maximum allowed size. doc_url: >- https://vexioncards.mintlify.site/api-reference/errors#request_too_large request_id: req_5f8b2c4a9e1d3 '422': description: Semantically invalid input. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limited - respect Retry-After. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Server error. Retry-safe on idempotent calls. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: api_error code: internal_error message: >- An internal error occurred. The request may be retried with the same Idempotency-Key. doc_url: >- https://vexioncards.mintlify.site/api-reference/errors#internal_error request_id: req_5f8b2c4a9e1d3 examples: Http 500 default: summary: Http 500 default value: error: type: api_error code: internal_error message: >- An internal error occurred. The request may be retried with the same Idempotency-Key. doc_url: >- https://vexioncards.mintlify.site/api-reference/errors#internal_error request_id: req_5f8b2c4a9e1d3 headers: {} components: schemas: ProductCreateRequest: type: object description: >- Create a manual catalog entry. POS-sourced entries cannot be created via API - they arrive through the location's POS sync. Server-owned fields (`pos_ref`, `source`) are rejected with `422 parameter_unknown`. required: - location_id - name properties: location_id: type: string pattern: ^loc_[A-Za-z0-9]+$ description: The location catalog to add to. Must belong to your organization. example: loc_01HW9R4P2ZK7N8MTX1RVLOCS01 name: anyOf: - type: string title: Single name (all languages) minLength: 1 maxLength: 200 - type: object title: Per-language names additionalProperties: type: string minLength: 1 maxLength: 200 minProperties: 1 description: >- Keys are language codes (`sk`, `cs`, `en`, `de`). Resolution: customer language → organization default language → any. description: >- Display name - plain string or per-language object, the same localization pattern as `Card.name`. POS-synced entries arrive with the till's single-language name; supply per-language names on manual/API entries when your audience is multilingual (border stores, tourist areas). Notifications and future product-facing surfaces resolve the name in the customer's language. example: Flat White sku: type: - string - 'null' minLength: 1 maxLength: 64 description: >- Strongly recommended - the correlation key line items resolve on. Unique per location (`409 sku_already_exists` on collision). example: FW-12 category: type: - string - 'null' minLength: 1 maxLength: 100 description: Free-form category. tags: type: array items: type: string description: >- Your own filing labels. They join the product name in the `search` haystack, so a tag makes the product findable even when the search text appears nowhere in its name. Omit for none. price_minor: type: - integer - 'null' minimum: 0 description: Reference price in minor units. Maximum 100,000,000,000. maximum: 100000000000 example: location_id: loc_01HW9R4P2ZK7N8MTX1RVLOCS01 name: Flat White sku: FW-12 category: drinks price_minor: 350 Product: type: object description: >- A catalog entry for correlating transaction line items to real products. **Catalogs are per-location** (each location can run a different POS with a different menu), unified under the organization: list org-wide, filter by `location_id`. This is a loyalty correlation catalog, not an inventory system - no variants, modifiers, or stock levels. required: - id - object - location_id - name - source - is_active - created_at properties: id: type: string pattern: ^prd_[A-Za-z0-9]+$ description: >- Product identifier, `prd_` prefix. Stable forever - line items resolve to it. example: prd_01HW9R7T2CD8N8MTX1RVPRDFW1 object: type: string const: product description: Always `"product"`. location_id: type: string pattern: ^loc_[A-Za-z0-9]+$ description: >- The location this catalog entry belongs to. The same drink sold at two locations is two Product records (each mapped to its own POS). example: loc_01HW9R4P2ZK7N8MTX1RVLOCS01 name: anyOf: - type: string title: Single name (all languages) minLength: 1 maxLength: 200 - type: object title: Per-language names additionalProperties: type: string minLength: 1 maxLength: 200 minProperties: 1 description: >- Keys are language codes (`sk`, `cs`, `en`, `de`). Resolution: customer language → organization default language → any. description: >- Display name - plain string or per-language object, the same localization pattern as `Card.name`. POS-synced entries arrive with the till's single-language name; supply per-language names on manual/API entries when your audience is multilingual (border stores, tourist areas). Notifications and future product-facing surfaces resolve the name in the customer's language. example: Flat White sku: type: - string - 'null' minLength: 1 maxLength: 64 description: >- Your stable key, **unique per location** (two locations may both use `FW-12`). This is what transaction line items correlate on. example: FW-12 category: type: - string - 'null' minLength: 1 maxLength: 100 description: Free-form category for basket analytics. example: drinks tags: type: array items: type: string description: >- Merchant-owned filing aid, and part of the `search` haystack alongside the name. NEVER populated by POS sync: no POS system sends tags, so a `source: "pos"` entry arrives untagged. You can tag one yourself with PATCH /v1/products/{id} (tags are an overlay field, unlike `pos_ref` and `source`, which sync owns), and it becomes findable by that tag immediately. Sending `[]` clears them and removes them from the search haystack. example: - coffee - hot price_minor: type: - integer - 'null' minimum: 0 description: >- Reference price in minor units. Informational - the POS bill is authoritative at transaction time. example: 350 source: type: string description: >- Where this catalog entry originated. Known values: `pos` (synced from the location's connected POS), `manual` (dashboard), `api` (created via POST /v1/products). Server-stamped - treat as an open set. example: pos pos_ref: type: - object - 'null' description: >- The POS mapping for this location's adapter. **Read-only, owned by the sync** - never editable via API. Null for manual/API entries. The POS vendor name is never surfaced. properties: external_product_id: type: string description: The product id in the location's POS. example: p:nazlrMDNh example: null is_active: type: boolean description: >- False = archived (delisted from the POS or manually retired). Archived products stay resolvable on historical line items - there is no hard delete. example: true created_at: type: integer description: Unix seconds. example: 1750000000 updated_at: type: integer description: Unix seconds of last change. example: 1750000000 Error: type: object required: - error properties: error: type: object required: - type - code - message properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - not_found_error - rate_limit_error - idempotency_error - api_error code: type: string message: type: string retry_after: type: integer description: >- Seconds to wait before retrying. Present on rate-limit (429) and idempotency-key-in-use (409) errors; mirrors the `Retry-After` HTTP header. Absent on error types that carry no retry guidance. example: 5 param: type: - string - 'null' request_id: type: string doc_url: type: string format: uri field_errors: type: array description: >- Per-field errors on a 422. At most 100 entries: a request with more errors gets the first 100. items: type: object properties: param: type: string code: type: string message: type: string expected_currency: type: string description: >- On `currency_mismatch`: the business currency the request must use. Absent on every other field error. description: >- The error payload: type (category), code (machine-readable), message (human-readable), retry_after (seconds, on rate-limit/idempotency-in-use errors only), param (offending field), request_id, doc_url, field_errors[]. description: >- Standard error envelope. Branch on `error.code`; include `error.request_id` in support requests. See the Errors guide. securitySchemes: apiKey: type: http scheme: bearer description: >- Your secret API key as a Bearer token: `Authorization: Bearer vxn_sk_...`. Keys are created and scoped in the dashboard - see [Authentication](/api-reference/introduction#authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.