Stripe: Create a Calculation

← Tax operations · Get started

Operation stripe.posttaxcalculations

Provider route: POST /v1/tax/calculations. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { StripeIntegration } from "@alter-ai/stripe";

async function execute(input: Parameters<StripeIntegration["tax"]["postTaxCalculations"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.tax.postTaxCalculations(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_stripe import StripeIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.tax.post_tax_calculations(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
headers	object	Optional	Additional keys: not allowed
headers.Idempotency-Key	string	Optional	Minimum length: 1 Maximum length: 255
body	object	Required within parent	Additional keys: not allowed
body.currency	string	Required within parent	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency
body.customer	string	Optional	The ID of an existing customer to use for this calculation. If provided, the customer’s address and tax IDs are copied to `customer_details`. Maximum length: 5000
body.customer_details	object	Optional	Details about the customer, including address and tax IDs.
body.customer_details.address	Model	Optional	Expand Create a Calculation — request body — body customer details address
body.customer_details.address_source	string	Optional	One of: billing, shipping
body.customer_details.ip_address	string	Optional
body.customer_details.tax_ids	array	Optional
body.customer_details.tax_ids[]	Model	Each item	Expand Create a customer — request body — body tax id data item
body.customer_details.taxability_override	string	Optional	One of: customer_exempt, none, reverse_charge
body.expand	array	Optional	Specifies which fields in the response should be expanded.
body.expand[]	string	Each item	Maximum length: 5000
body.line_items	array	Required within parent	A list of items the customer is purchasing. You can pass up to 100 line items, or 1,000 if your account has an increased limit.
body.line_items[]	object	Each item
body.line_items[].amount	integer	Required within parent
body.line_items[].metadata	object	Optional	Additional keys: see wildcard field
body.line_items[].metadata.*	string	Additional keys
body.line_items[].performance_location	string	Optional	Maximum length: 5000
body.line_items[].product	string	Optional	Maximum length: 5000
body.line_items[].quantity	integer	Optional
body.line_items[].reference	string	Optional	Maximum length: 500
body.line_items[].tax_behavior	string	Optional	One of: exclusive, inclusive
body.line_items[].tax_code	string	Optional
body.ship_from_details	object	Optional	Details about the address from which the goods are being shipped.
body.ship_from_details.address	Model	Required within parent	Expand Create a Calculation — request body — body customer details address
body.shipping_cost	object	Optional	Shipping cost details to be used for the calculation.
body.shipping_cost.amount	integer	Optional
body.shipping_cost.shipping_rate	string	Optional	Maximum length: 5000
body.shipping_cost.tax_behavior	string	Optional	One of: exclusive, inclusive
body.shipping_cost.tax_code	string	Optional
body.tax_date	integer	Optional	The calculation uses the tax rules and rates that are in effect at this timestamp. You can use a date up to 31 days in the past or up to 31 days in the future. If you use a future date, Stripe doesn’t guarantee that the expected tax rules and rate being used match the actual rules and rate that will be in effect on that date. We deploy tax changes before their effective date, but not within a fixed window.

Referenced models: Create a Calculation — request body — body customer details address, Create a customer — request body — body tax id data item

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Create a Calculation — response body

Referenced models: Create a Calculation — response body

Schemas

11 more schemas are linked from the tables above, on the schema pages.

Create a Calculation — response body

Field	Type	Presence	Description and constraints
$	object	Root	A Tax Calculation allows you to calculate the tax to collect from your customer. Related guide: [Calculate tax in your custom payment flow](https://docs.stripe.com/tax/custom)
amount_total	JSON	Required within parent
amount_total (anyOf 1)	integer	Alternative	Total amount after taxes in the [smallest currency unit](https://docs.stripe.com/currencies#minor-units).
amount_total (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
currency	string	Required within parent	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Maximum length: 5000
customer	JSON	Optional
customer (anyOf 1)	string	Alternative	The ID of an existing [Customer](https://docs.stripe.com/api/customers/object) used for the resource. Maximum length: 5000
customer (anyOf 2)	null	Alternative
customer_details	Model	Required within parent	Expand Create a Calculation — response body — customer details
expires_at	JSON	Optional
expires_at (anyOf 1)	JSON	Alternative
expires_at (anyOf 1) (anyOf 1)	integer	Alternative	Timestamp of date at which the tax calculation will expire. Format: unix-time
expires_at (anyOf 1) (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
expires_at (anyOf 2)	null	Alternative
id	JSON	Optional
id (anyOf 1)	string	Alternative	Unique identifier for the calculation. Maximum length: 5000
id (anyOf 2)	null	Alternative
line_items	JSON	Optional
line_items (anyOf 1)	object	Alternative	The list of items the customer is purchasing.
line_items (anyOf 1).data	array	Required within parent	Details about each object.
line_items (anyOf 1).data[]	Model	Each item	Expand Retrieve a Calculation's line items — response body — data item
line_items (anyOf 1).has_more	boolean	Required within parent	True if this list has another page of items after this one that can be fetched.
line_items (anyOf 1).object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Always has the value `list`. Known values: list
line_items (anyOf 1).url	string	Required within parent	The URL where this list can be accessed. Maximum length: 5000 Pattern: ^/v1/tax/calculations/[^/]+/line_items
line_items (anyOf 2)	null	Alternative
livemode	boolean	Required within parent	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: tax.calculation
ship_from_details	JSON	Optional
ship_from_details (anyOf 1)	JSON	Alternative	The details of the ship from location, such as the address.
ship_from_details (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create a Calculation — response body — ship from details value address
ship_from_details (anyOf 2)	null	Alternative
shipping_cost	JSON	Optional
shipping_cost (anyOf 1)	JSON	Alternative	The shipping cost details for the calculation.
shipping_cost (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create a Calculation — response body — shipping_cost / The shipping cost details for the calculation / tax_behavior: exclusive, inclusive
shipping_cost (anyOf 2)	null	Alternative
tax_amount_exclusive	JSON	Required within parent
tax_amount_exclusive (anyOf 1)	integer	Alternative	The amount of tax to be collected on top of the line item prices.
tax_amount_exclusive (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
tax_amount_inclusive	JSON	Required within parent
tax_amount_inclusive (anyOf 1)	integer	Alternative	The amount of tax already included in the line item prices.
tax_amount_inclusive (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
tax_breakdown	array	Required within parent	Breakdown of individual tax amounts that add up to the total.
tax_breakdown[]	Model	Each item	Expand Create a Calculation — response body — tax breakdown item
tax_date	JSON	Required within parent
tax_date (anyOf 1)	integer	Alternative	The calculation uses the tax rules and rates that are in effect at this timestamp. You can use a date up to 31 days in the past or up to 31 days in the future. If you use a future date, Stripe doesn't guarantee that the expected tax rules and rate being used match the actual rules and rate that will be in effect on that date. We deploy tax changes before their effective date, but not within a fixed window. Format: unix-time
tax_date (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Referenced models: Retrieve a Calculation's line items — response body — data item, Create a Calculation — response body — customer details, Create a Calculation — response body — ship from details value address, Create a Calculation — response body — tax breakdown item, Create a Calculation — response body — shipping_cost / The shipping cost details for the calculation / tax_behavior: exclusive, inclusive

Create a Calculation — request body — body customer details address

Field	Type	Presence	Description and constraints
$	object	Root
city	JSON	Optional
city (anyOf 1)	string	Alternative	Maximum length: 5000
city (anyOf 2)	string	Alternative	One of:
country	string	Required within parent	Maximum length: 5000
line1	JSON	Optional
line1 (anyOf 1)	string	Alternative	Maximum length: 5000
line1 (anyOf 2)	string	Alternative	One of:
line2	JSON	Optional
line2 (anyOf 1)	string	Alternative	Maximum length: 5000
line2 (anyOf 2)	string	Alternative	One of:
postal_code	JSON	Optional
postal_code (anyOf 1)	string	Alternative	Maximum length: 5000
postal_code (anyOf 2)	string	Alternative	One of:
state	JSON	Optional
state (anyOf 1)	string	Alternative	Maximum length: 5000
state (anyOf 2)	string	Alternative	One of:

Create a customer — request body — body tax id data item

Field	Type	Presence	Description and constraints
$	object	Root
type	string	Required within parent	One of: ad_nrt, ae_trn, al_tin, am_tin, ao_tin, ar_cuit, au_abn, au_arn, aw_tin, az_tin, ba_tin, bb_tin, bd_bin, bf_ifu, bg_uic, bh_vat, bj_ifu, bo_tin, br_cnpj, br_cpf, bs_tin, by_tin, ca_bn, ca_gst_hst, ca_pst_bc, ca_pst_mb, ca_pst_sk, ca_qst, cd_nif, ch_uid, ch_vat, cl_tin, cm_niu, cn_tin, co_nit, cr_tin, cv_nif, de_stn, do_rcn, ec_ruc, eg_tin, es_cif, et_tin, eu_oss_vat, eu_vat, fo_vat, gb_vat, ge_vat, gi_tin, gn_nif, hk_br, hr_oib, hu_tin, ic_nif, id_npwp, il_vat, in_gst, is_vat, it_cf, jp_cn, jp_rn, jp_trn, ke_pin, kg_tin, kh_tin, kr_brn, kz_bin, la_tin, li_uid, li_vat, lk_vat, ma_vat, md_vat, me_pib, mk_vat, mr_nif, mx_rfc, my_frp, my_itn, my_sst, ng_tin, no_vat, no_voec, np_pan, nz_gst, om_vat, pe_ruc, ph_tin, pl_nip, py_ruc, ro_tin, rs_pib, ru_inn, ru_kpp, sa_vat, sg_gst, sg_uen, si_tin, sn_ninea, sr_fin, sv_nit, th_vat, tj_tin, tr_tin, tw_vat, tz_vat, ua_vat, ug_tin, us_ein, uy_ruc, uz_tin, uz_vat, ve_rif, vn_tin, za_vat, zm_tin, zw_tin Maximum length: 5000
value	string	Required within parent

Create a Calculation — response body — customer details

Field	Type	Presence	Description and constraints
$	object	Root
address	JSON	Optional
address (anyOf 1)	JSON	Alternative	The customer's postal address (for example, home or business location).
address (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create a Calculation — response body — ship from details value address address
address (anyOf 2)	null	Alternative
address_source	JSON	Optional
address_source (anyOf 1)	string	Alternative	The type of customer address provided. Known values: billing, shipping
address_source (anyOf 2)	null	Alternative
ip_address	JSON	Optional
ip_address (anyOf 1)	string	Alternative	The customer's IP address (IPv4 or IPv6). Maximum length: 5000
ip_address (anyOf 2)	null	Alternative
tax_ids	array	Required within parent	The customer's tax IDs (for example, EU VAT numbers).
tax_ids[]	Model	Each item	Expand Create a Calculation — response body — customer details tax ids item
taxability_override	string	Required within parent	The taxability override used for taxation. Known values: customer_exempt, none, reverse_charge

Referenced models: Create a Calculation — response body — customer details tax ids item, Create a Calculation — response body — ship from details value address address

Policy, approvals and errors

SDK function policy ID: stripe.posttaxcalculations. Catalog operation: PostTaxCalculations. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Stripe-Version": "2026-09-30.endive"}

Official provider source