> ## Documentation Index > Fetch the complete documentation index at: https://alguna.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Calculate tax > Computes tax for inline line items against your legal entity's configured tax engine and stores the result, returning an id (with an expiry) you pass when issuing a receipt to pin these exact line items and amounts. Each call creates a new calculation; send an `Idempotency-Key` header to make a retry return the original calculation instead of a new one. Provide a buyer address (and optional tax ids for reverse-charge / exemption) and per-line canonical tax codes; an omitted code defaults to general business SaaS. ## OpenAPI ````yaml /api-reference/v2/specs/2026-04-01.json post /tax/calculations openapi: 3.1.0 info: description: >- Alguna is the AI-native quote-to-revenue platform for B2B companies: CPQ, subscription and usage-based billing, invoicing, payment collection, and revenue recognition in one system of record. The API operates on one versioned agreement per customer: quotes, subscriptions and their versions, usage, invoices, payments, and revenue schedules read from it. Official SDKs: TypeScript (@alguna/sdk), Python (alguna), Go (github.com/alguna-io/alguna-go), Rust (alguna), and the alguna CLI (@alguna/cli). title: Alguna Public API version: '2026-04-01' servers: - url: https://api.alguna.io x-fern-server-name: Production security: - bearerAuth: [] tags: - name: Billing Events and Metrics - name: Checkout Sessions - name: Credit Notes - name: Credits - name: Customer Portal Sessions - name: Customers - name: Feedback - name: Insights - name: Integrations - name: Invoices - name: Merchants - name: Payments - name: Plans - name: Product Bundles - name: Products - name: Quotes - name: Refunds - name: Revenue Schedules - name: Subscription Changes - name: Subscription Versions - name: Subscriptions - name: Tags - name: Tax - name: Users - name: Wallet Grants - name: Wallets paths: /tax/calculations: post: tags: - Tax summary: Calculate tax description: >- Computes tax for inline line items against your legal entity's configured tax engine and stores the result, returning an id (with an expiry) you pass when issuing a receipt to pin these exact line items and amounts. Each call creates a new calculation; send an `Idempotency-Key` header to make a retry return the original calculation instead of a new one. Provide a buyer address (and optional tax ids for reverse-charge / exemption) and per-line canonical tax codes; an omitted code defaults to general business SaaS. operationId: create-tax-calculation parameters: - in: header name: Alguna-Version required: true schema: enum: - '2026-04-01' type: string - in: header name: Idempotency-Key schema: description: >- A unique string that makes a retried write safe. If you send the same request with the same key within 24 hours, the API returns the stored response and does not run the request again. A 5xx or 429 response is not stored, so a retry with that key runs the request again. example: ik_a1b2c3d4e5f6 maxLength: 255 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateTaxCalculationRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/TaxCalculationResponse' description: Success headers: Idempotency-Key: description: Echo of the idempotency key provided in the request schema: type: string Idempotent-Replayed: description: >- Whether this response was replayed from a previous request (true) or freshly executed (false) schema: type: boolean '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Bad Request '401': content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorResponse' - $ref: '#/components/schemas/GatewayErrorResponse' description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Forbidden — the organization does not have access to this feature '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not Found '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Conflict — a request with this idempotency key is currently being processed headers: Retry-After: description: >- Seconds to wait before retrying with the same idempotency key. Sent only when a request with this key is still being processed; a 409 without it is a conflict that a retry will not resolve. schema: type: integer '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Entity '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error '502': description: >- Bad Gateway — sent by the infrastructure in front of the API; the body is not JSON. Safe to retry. '503': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Service Unavailable — a dependency is temporarily unavailable. Retry with backoff. '504': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Gateway Timeout — the request did not finish in time. Retry with backoff; use an idempotency key for writes. components: schemas: CreateTaxCalculationRequest: properties: currency: description: ISO 4217 currency code example: USD type: string customer: allOf: - $ref: '#/components/schemas/TaxCalculationCustomerRequest' description: Who is being taxed legal_entity_id: description: Selling legal entity; defaults to the org's default when omitted nullable: true type: string line_items: description: Line items to tax items: $ref: '#/components/schemas/TaxCalculationLineItemRequest' minItems: 1 type: array merchant_id: description: >- Existing sub-merchant the receipt is issued for; you remain the seller of record. Create the merchant before referencing it here. Requires the merchants entitlement example: mrch_01H8XGJWBWBAQ4PLwXYZ nullable: true type: string tax_behavior: allOf: - $ref: '#/components/schemas/TaxBehavior' description: Whether line amounts exclude (default) or already include tax example: exclusive nullable: true required: - currency - customer - line_items type: object TaxCalculationResponse: properties: currency: description: Currency of the amounts type: string expires_at: description: When the calculation stops being issuable format: date-time type: string id: description: >- Id of the persisted calculation; pass it when issuing a receipt to pin these results type: string line_items: description: Per-line tax breakdown items: $ref: '#/components/schemas/TaxCalculationLineResponse' type: array merchant_id: description: >- Sub-merchant the calculation was made for; a document issued from it inherits this attribution example: mrch_01H8XGJWBWBAQ4PLwXYZ nullable: true type: string total_tax: description: Sum of per-line tax amounts type: string required: - currency - expires_at - id - line_items - total_tax type: object ErrorResponse: description: The body of every error the API returns. properties: detail: description: Explanation of what went wrong type: string status: description: HTTP status code of the response format: int64 type: integer title: description: >- HTTP status text. Sent only by version, idempotency and credit-refusal errors. type: string type: description: Always `about:blank`. Sent only by version and idempotency errors. type: string required: - status - detail type: object GatewayErrorResponse: description: >- Returned by the API gateway when a request carries no valid API key, before the API handles it. properties: code: description: Machine-readable error code, e.g. `unauthenticated` type: string details: nullable: true type: object message: description: Explanation of what went wrong type: string required: - code - message type: object TaxCalculationCustomerRequest: properties: address: allOf: - $ref: '#/components/schemas/TaxCalculationAddressRequest' description: Customer address used for tax determination email: description: Customer email; the receipt recipient, frozen for issuance example: buyer@example.com format: email nullable: true type: string first_name: description: Customer first name; frozen for issuance to name/contact the account example: Jane minLength: 1 type: string last_name: description: Customer last name; frozen for issuance to name/contact the account example: Doe minLength: 1 type: string reference: description: Customer reference (e.g. your customer id) nullable: true type: string tax_ids: description: Customer tax ids for reverse-charge / exemption items: $ref: '#/components/schemas/TaxCalculationTaxIDRequest' type: array required: - address - first_name - last_name type: object TaxCalculationLineItemRequest: properties: amount: description: Per-unit amount; line total is amount * quantity example: '100.00' type: string billing_period_end: description: >- End of the service period this line covers, exclusive: for a period through 31 January send 2026-02-01T00:00:00Z, which the invoice prints as 31 January. Carried onto the invoice line minted from this calculation. Send with billing_period_start. example: '2026-02-01T00:00:00Z' format: date-time nullable: true type: string billing_period_start: description: >- Start of the service period this line covers, inclusive. Carried onto the invoice line minted from this calculation. Send with billing_period_end. example: '2026-01-01T00:00:00Z' format: date-time nullable: true type: string description: description: Human-readable line description example: Pro plan type: string quantity: description: Quantity example: '1' type: string reference: description: >- Your reference for the line; echoed back on the matching result line. Generated when omitted. example: line_1 type: string tax_code: description: Canonical tax code; defaults to general when omitted example: txcd_business_saas nullable: true type: string required: - amount - quantity type: object TaxBehavior: enum: - exclusive - inclusive type: string TaxCalculationLineResponse: properties: billing_period_end: description: >- End of the service period sent for this line, exclusive. The invoice minted from this calculation prints the preceding day. format: date-time nullable: true type: string billing_period_start: description: Start of the service period sent for this line, inclusive format: date-time nullable: true type: string reference: description: >- Echoes the reference from the matching request line (or the generated one) type: string tax_amount: description: Tax amount for the line example: '6.60' type: string tax_rate: description: >- Combined tax rate applied across jurisdictions, as a percentage (8.25 = 8.25%). Where a jurisdiction taxes only part of the line, tax_amount reflects that taxable portion, so tax_rate multiplied by the line amount may exceed tax_amount. example: '8.25' type: string tax_reason: allOf: - $ref: '#/components/schemas/TaxabilityReason' description: Reason determining how tax was applied nullable: true tax_type: allOf: - $ref: '#/components/schemas/TaxType' description: Type of tax applied nullable: true taxable_amount: description: >- Portion of the line the tax rate was applied to. Equals the line total unless a jurisdiction taxes only part of it (Texas taxes 80% of SaaS); zero when no tax was applied. example: '80.00' type: string required: - tax_amount - tax_rate - taxable_amount type: object TaxCalculationAddressRequest: properties: city: description: City example: San Francisco type: string country: description: ISO 3166-1 alpha-3 country code example: USA type: string line1: description: Street address line 1 example: 123 Main St type: string line2: description: Street address line 2 example: Suite 100 type: string postal_code: description: Postal or ZIP code; required for US addresses example: '94105' type: string state: description: >- State or province. For US and Canadian addresses, a two-letter code or the full name; the calculation stores the code. Any other value is rejected. example: CA type: string required: - country type: object TaxCalculationTaxIDRequest: properties: type: description: Tax id type, e.g. eu_vat, gb_vat, us_ein example: eu_vat type: string value: description: Tax id value example: DE123456789 type: string required: - type - value type: object TaxabilityReason: enum: - standard_rated - reverse_charge - not_collecting - customer_exempt - zero_rated - other type: string TaxType: enum: - gst - hst - igst - jct - lease_tax - pst - qst - sales_tax - service_tax - vat type: string securitySchemes: bearerAuth: bearerFormat: API Key description: API key authentication. Pass your API key as a Bearer token. scheme: bearer type: http x-fern-bearer: env: ALGUNA_API_KEY name: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.