> ## 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: title: Alguna Public API version: '2026-04-01' servers: - url: https://api.alguna.io security: - bearerAuth: [] tags: - name: Billing Events and Metrics - name: Credit Notes - name: Credits - name: Customer Portal Sessions - name: Customers - name: Insights - name: Invoices - name: Payments - name: Plans - name: Product Bundles - name: Products - name: Refunds - name: Revenue Schedules - name: Subscription Changes - name: Subscription Versions - name: Subscriptions - name: Tax - 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 used to ensure the request is processed exactly once. If you retry a request with the same idempotency key within 24 hours, the original response is returned without re-executing the operation. 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: $ref: '#/components/schemas/ErrorResponse' description: Unauthorized '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 '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 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' type: array tax_behavior: description: Whether line amounts exclude (default) or already include tax enum: - exclusive - inclusive example: exclusive nullable: true type: string 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 total_tax: description: Sum of per-line tax amounts type: string required: - currency - expires_at - id - line_items - total_tax type: object ErrorResponse: properties: detail: type: string status: format: int64 type: integer required: - status - detail 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 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 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 TaxCalculationLineResponse: properties: reference: description: >- Echoes the reference from the matching request line (or the generated one) type: string tax_amount: description: Tax amount for the line type: string tax_rate: description: Tax rate applied, as a decimal fraction (0.20 = 20%) type: string tax_reason: description: Reason determining how tax was applied nullable: true type: string tax_type: description: Type of tax applied nullable: true type: string required: - tax_amount - tax_rate 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 example: '94105' type: string state: description: State or province 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 securitySchemes: bearerAuth: bearerFormat: API Key description: API key authentication. Pass your API key as a Bearer token. scheme: bearer type: http ````