> ## Documentation Index > Fetch the complete documentation index at: https://docs.taberna.io/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Taberna is a crypto payments API. Amounts are priced in fiat (USD or EUR) and paid in crypto. > Fiat amounts are ALWAYS decimal strings ("9.99"), never numbers. Crypto amounts are integer strings in the asset's smallest unit. > Authenticate merchant endpoints with `Authorization: Bearer tbrn_live_...`. Every key is bound to one store and carries an explicit scope set, so never pass a store id to a /v1 endpoint. > A 401 means the credential is bad; a 403 means the key lacks a scope. Never retry or re-authenticate on a 403 — surface it as a configuration error. > The /v1/checkouts endpoints are deliberately unauthenticated and run in the buyer's browser. Never send an API key to a browser. > Verify webhook signatures over the RAW request body before parsing JSON, and treat delivery as at-least-once: handlers must be idempotent. > Never grant value based on a browser redirect to successUrl. Fulfil on a signature-verified webhook, or on a server-side read of GET /v1/orders/{id} or GET /v1/invoices/{id}. > There is no test mode: every payment method is a live chain moving real funds. > A merchant can run an entire shop with no code: the dashboard creates products and invoices, and every store can host a storefront at {slug}.taberna.io with its own theme, sections, branding and optional custom domain. Never assume the reader has an API integration. > Taberna issues no refunds and performs no KYC. A refund is something the merchant sends from their own payout wallet, off-platform. # Add stock to a product > Appends delivery stock to a `text_pool` product. Requires the `products:write` scope. Send the units as one `text` blob; it is split on the product's configured delimiter, trimmed, and deduplicated against the units already available or reserved. Lines that collide are reported as `skippedDuplicates` rather than rejected, so re-sending a batch is safe. Any other delivery type is a 400. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/products/{id}/stock openapi: 3.1.0 info: title: Taberna API description: >- Accept crypto payments for digital goods. Create orders and invoices, hand the buyer a hosted checkout link, and let webhooks tell you when the money lands. Authenticate merchant endpoints with a store API key as a bearer token (`Authorization: Bearer tbrn_live_…`). Every key is bound to one store and carries an explicit set of scopes; the scope a route requires is stated in its description and in the `x-required-scope` extension. A key without the scope gets a 403 — mint one with the scope rather than retrying. The Checkout endpoints are the exception: they are unauthenticated and meant to be called from the buyer's browser. Possession of the checkout id is the credential there, so never ship an API key to a page. Conventions: ids in links are short ids; fiat amounts are decimal strings ("9.99"); crypto amounts are integer strings in the asset's smallest unit; timestamps are ISO-8601 UTC. Errors carry `{ "error": "…" }` unless documented otherwise. version: 1.0.0 servers: - url: https://api.taberna.io description: Taberna API security: [] tags: - name: Orders description: Carts of products, paid through a hosted checkout. - name: Invoices description: Merchant-issued bills with their own payment page. - name: Invoice Templates description: Saved invoice presets, referenced by `templateId` when creating one. - name: Products description: Catalogue reads and delivery stock top-ups. - name: Store description: What the calling API key is and what it may do. - name: Webhook Deliveries description: Delivery history for the store webhook, and replay. - name: Checkout description: >- Buyer-facing hosted-page endpoints. Unauthenticated by design — never send an API key. paths: /v1/products/{id}/stock: post: tags: - Products summary: Add stock to a product description: >- Appends delivery stock to a `text_pool` product. Requires the `products:write` scope. Send the units as one `text` blob; it is split on the product's configured delimiter, trimmed, and deduplicated against the units already available or reserved. Lines that collide are reported as `skippedDuplicates` rather than rejected, so re-sending a batch is safe. Any other delivery type is a 400. operationId: postV1ProductsByIdStock parameters: - in: path name: id schema: type: string format: uuid example: 3f1a9c2e-7b04-4d8e-9a6f-2c5b1e0d7a83 required: true description: >- The product to act on. Formatted as a UUID, e.g. `3f1a9c2e-7b04-4d8e-9a6f-2c5b1e0d7a83`. requestBody: required: true content: application/json: schema: type: object properties: text: type: string minLength: 1 maxLength: 5000000 description: >- The new stock units as one blob, split on the product's configured delimiter (a newline, by default). Lines are trimmed, and any that duplicate a unit already available or reserved are reported as `skippedDuplicates` rather than rejected — so re-sending a batch is safe. Up to 5,000,000 characters, subject to the 8MB body limit. example: |- ACME-9F2K-77QX ACME-3B1M-52TD required: - text responses: '200': description: >- How many units were added, skipped as duplicates, and are now available. content: application/json: schema: type: object properties: added: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Units accepted into the pool by this call. example: 120 skippedDuplicates: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Units dropped because an identical one was already available or reserved. Re-sending a batch is therefore safe. example: 5 available: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Units now sellable in the pool, after this call. example: 162 required: - added - skippedDuplicates - available description: >- The result of appending delivery stock to a `text_pool` product. example: added: 120 skippedDuplicates: 5 available: 162 '400': description: >- The request failed validation (`{ "error": "Invalid request data" }`), or the operation is not allowed in the resource's current state. content: application/json: schema: type: object properties: error: type: string description: >- Human-readable explanation of what went wrong. Meant for logs and developers, not for branching — switch on the HTTP status instead. example: Order not found required: - error description: The standard error body, returned by every failing endpoint. example: error: Order not found '401': description: >- Missing, malformed, revoked or expired API key. The `WWW-Authenticate` header names the challenge that failed. content: application/json: schema: type: object properties: error: type: string description: >- Human-readable explanation of what went wrong. Meant for logs and developers, not for branching — switch on the HTTP status instead. example: Order not found required: - error description: The standard error body, returned by every failing endpoint. example: error: Order not found '403': description: The key is valid but was not granted the scope this route requires. content: application/json: schema: type: object properties: error: type: string description: >- Human-readable explanation of what went wrong. Meant for logs and developers, not for branching — switch on the HTTP status instead. example: Order not found required: - error description: The standard error body, returned by every failing endpoint. example: error: Order not found '404': description: >- No such product for this API key's store. Resources belonging to another store are reported as missing, never as forbidden. content: application/json: schema: type: object properties: error: type: string description: >- Human-readable explanation of what went wrong. Meant for logs and developers, not for branching — switch on the HTTP status instead. example: Order not found required: - error description: The standard error body, returned by every failing endpoint. example: error: Order not found '413': description: >- The request body exceeded the 8MB limit (`{ "error": "Payload too large" }`). Note that the limit is on encoded bytes, so a body can hit it below the field's character limit. content: application/json: schema: type: object properties: error: type: string description: >- Human-readable explanation of what went wrong. Meant for logs and developers, not for branching — switch on the HTTP status instead. example: Order not found required: - error description: The standard error body, returned by every failing endpoint. example: error: Order not found security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- A store API key, sent as `Authorization: Bearer `. A key looks like `tbrn_live_` followed by 48 hex characters, e.g. `tbrn_live_4f2a...c91b`. Mint one in the Taberna dashboard under Developers → API Keys, tick the scopes the integration needs, and copy it there and then — the full value is shown once and only its hash is stored, so a lost key is replaced rather than recovered. One key belongs to one store and carries a fixed scope set. Send it from a server, never from a browser: it can create orders and invoices and read every order the store has. ````