> ## Documentation Index > Fetch the complete documentation index at: https://docs.beinfi.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a product > Creates the product together with version 1 in `draft`. To sell it, publish that version with `POST /products/{productID}/versions/{versionID}/publish`. With a `key`, the call is idempotent: if the key already exists you get the product it identifies (with `name` and `description` updated to what you sent) instead of an error. Pricing is not part of that update: if `basePrice` or `billingCycle` differ from the current version, the response is `422 pricing_immutable`. To change the price, create a new version with `POST /products/{productID}/versions`. A request that sends no pricing leaves pricing alone. ## OpenAPI ````yaml /api-reference/openapi.en.json post /products openapi: 3.1.0 info: title: Infi API version: 0.0.1 description: > The Infi REST API: catalog, customers, usage metering, subscriptions, invoices, payments and checkout. **Authentication.** Send your secret key as `Authorization: Bearer sk_test_…` (sandbox) or `sk_live_…` (production). The key prefix selects the environment. Checkout routes (`/pay/*`) and `/public/*` take no key: they run in the payer's browser. **Idempotency.** Every request that changes data requires an `Idempotency-Key` header. A retry with the same key returns the original response instead of running again. **Amounts.** Money and quantities travel as decimal strings (`"150.00"`, `"0.0001"`), never as floating-point numbers. **Errors.** The body carries `error_code` (stable, branch on it), `message` (for humans) and `tracer_id` (send it to support). Rate-limit and idempotency errors are nested under `error`, with `code` and `request_id`. servers: - url: https://api-sandbox.beinfi.com description: Sandbox - url: https://api.beinfi.com description: Production security: - bearerAuth: [] tags: - name: Catalog - name: Customers - name: Metering - name: Subscriptions - name: Invoices - name: Payments - name: Checkout - name: Coupons - name: Billing - name: Account - name: Webhooks - name: Test account - name: Rail - name: Storefronts paths: /products: post: tags: - Catalog summary: Create a product description: > Creates the product together with version 1 in `draft`. To sell it, publish that version with `POST /products/{productID}/versions/{versionID}/publish`. With a `key`, the call is idempotent: if the key already exists you get the product it identifies (with `name` and `description` updated to what you sent) instead of an error. Pricing is not part of that update: if `basePrice` or `billingCycle` differ from the current version, the response is `422 pricing_immutable`. To change the price, create a new version with `POST /products/{productID}/versions`. A request that sends no pricing leaves pricing alone. operationId: createProduct parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateProductRequest' responses: '201': content: application/json: schema: type: object properties: product: $ref: '#/components/schemas/Product' version: $ref: '#/components/schemas/Version' description: Product created (or the existing product with the same `key`). '401': $ref: '#/components/responses/Unauthorized' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/ValidationFailed' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false schema: type: string description: >- A unique key per operation (a UUID works). Retrying with the same key returns the original response. schemas: CreateProductRequest: type: object required: - name - pricingModel properties: key: type: - string - 'null' description: >- Stable product key, unique in your account. Creating twice with the same key returns the same product; pricing different from the current version is refused with `422 pricing_immutable`. name: type: string type: type: string enum: - agent - item description: '`item` (default) or `agent`.' description: type: - string - 'null' pricingModel: type: string enum: - subscription - one_time - usage - prepaid description: '`subscription`, `one_time`, `usage` or `prepaid`.' currency: type: string example: BRL description: '3-letter ISO 4217 code. Default: `BRL`.' billingCycle: type: - string - 'null' enum: - weekly - monthly - annual - null description: >- `weekly`, `monthly` or `annual`. Required for `subscription` and `prepaid`; omit it for other models. basePrice: type: - string - 'null' description: Version 1's base price, as a decimal string (`"49.90"`). Product: type: object properties: id: type: string format: uuid key: type: - string - 'null' description: >- A stable key you choose for the product, unique in your account. Lets you create the same product again without duplicating it. name: type: string type: type: string enum: - agent - item description: '`item` (default) or `agent`.' description: type: - string - 'null' pricingModel: type: string enum: - subscription - one_time - usage - prepaid description: >- How the product is charged: `subscription`, `one_time`, `usage` or `prepaid`. currency: type: string example: BRL description: 3-letter ISO 4217 code, such as `BRL`. status: type: string example: active description: '`active` or `archived`.' imageUrl: type: - string - 'null' description: Public address of the product photo. requiresShipping: type: boolean description: >- Whether the purchase requires physical delivery; when `true`, the checkout asks for an address. createdAt: type: string format: date-time updatedAt: type: string format: date-time description: A catalog entry. Pricing lives on the product's versions. Version: type: object properties: id: type: string format: uuid productId: type: string format: uuid version: type: integer description: Sequential version number (1, 2, 3…). billingCycle: type: - string - 'null' enum: - weekly - monthly - annual - null description: '`weekly`, `monthly` or `annual`; `null` for non-recurring products.' basePrice: type: - string - 'null' description: Base price as a decimal string; `null` for a usage-only product. status: type: string enum: - draft - published - archived description: >- `draft` (editable), `published` (sellable, fixed pricing) or `archived`. isDefault: type: boolean description: >- Whether this is the version a buyer gets when nothing names another. A published version with `isDefault: false` is an offer: it is only sold through a payment link created with `productVersionId`. publishedAt: type: - string - 'null' format: date-time commitmentAmount: type: - string - 'null' description: >- Minimum charged per cycle, as a decimal string; `null` when there is none. commitmentResets: type: boolean description: >- `true`: the unused minimum is lost at cycle close. `false`: it rolls over. consumptionFloor: type: - string - 'null' description: >- Balance below which usage recording is refused. See `VersionConsumption.floor`. grants: type: array items: $ref: '#/components/schemas/VersionGrant' description: Usage credits the version grants. description: >- A product version: a snapshot of its pricing. A published version never changes; to change the price, create another. VersionGrant: type: object required: - meter - amount - 'on' properties: meter: type: string description: >- The `name` of the meter credited (for example, `tokens`). `credits` is the general credits balance. amount: type: string description: Quantity to credit, as a decimal string. 'on': type: string enum: - cycle - payment description: >- `cycle`: at each new subscription period. `payment`: when the payment is confirmed. description: A usage credit granted by the version. Error: type: object required: - message - error_code - tracer_id properties: message: type: string description: Human-readable sentence. error_code: $ref: '#/components/schemas/ErrorCode' description: Stable error code. Branch on it. tracer_id: type: string description: Request id. Include it when contacting support. description: >- The standard error body. It is flat (no `error` wrapper) and the trace id is `tracer_id`. ConflictError: type: object required: - message - error_code - tracer_id - resource - metadata properties: message: type: string description: Human-readable explanation. error_code: $ref: '#/components/schemas/ErrorCode' description: Stable error code. Branch on this field. tracer_id: type: string description: Request identifier. Send it to support. resource: type: string description: The kind of resource in conflict. Empty string when not applicable. metadata: type: - object - 'null' additionalProperties: type: string description: Conflict details, as key-value pairs. `null` when there are none. description: 'Body of a 409 error: the resource''s state does not allow the operation.' RequestError: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string request_id: type: string ValidationError: type: object required: - message - error_code - tracer_id - errors properties: message: type: string error_code: $ref: '#/components/schemas/ErrorCode' tracer_id: type: string errors: type: array items: type: object required: - field - value - constraint - description properties: field: type: string value: type: string constraint: type: string description: type: string description: >- Per-field detail (`field`, `description`). Always present on a `422`; may be empty. description: >- Body of a `422`. Same shape as `Error`, plus `errors[]` with per-field detail. That is where the sentence telling you what to fix lives (for example, "product has no published version"). ErrorCode: type: string examples: - internal_error - validation_failed - bad_request - unauthorized - forbidden - not_found - conflict - rate_limited description: >- Stable error code. The list is open: besides the generic codes, each area defines its own (`coupon_expired`, `insufficient_balance`, `version_not_draft`, `idempotency_key_reused`…). Handle a code you do not recognize by its HTTP status and show `message`; do not fail parsing the response. responses: Unauthorized: content: application/json: schema: $ref: '#/components/schemas/Error' description: Missing or invalid API key. Conflict: content: application/json: schema: oneOf: - $ref: '#/components/schemas/ConflictError' - $ref: '#/components/schemas/RequestError' description: >- The resource's state does not allow the operation, or the `Idempotency-Key` was already used with a different body. ValidationFailed: content: application/json: schema: $ref: '#/components/schemas/ValidationError' description: One or more fields are invalid. Per-field detail is in `errors[]`. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your account's secret key: `Authorization: Bearer sk_test_…` or `sk_live_…`. Server-side only. ````