Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Payment Records
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

Tax Settings 

You can use Tax Settings to manage configurations used by Stripe Tax calculations.

Related guide: Using the Settings API

Endpoints

The Tax Setting object 

Attributes

  • objectstring

    String representing the object’s type. Objects of the same type share the same value.

  • defaultsobject

    Default configuration to be used on Stripe Tax calculations.

  • head_officenullable object

    The place where your business is located.

  • livemodeboolean

    Has the value true if the object exists in live mode or the value false if the object exists in test mode.

  • statusenum

    The status of the Tax Settings.

    Possible enum values
    active

    Tax Settings have the required information and ready for tax calculations.

    pending

    Tax Settings missing some required information and not ready for tax calculations. Check status_details field for more.

  • status_detailsobject

    Information about the status.

The Tax Setting object
{
  "object": "tax.settings",
  "defaults": {
    "tax_behavior": null,
    "tax_code": "txcd_10000000"
  },
  "head_office": {
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": "CA"
    }
  },
  "livemode": false,
  "status": "active",
  "status_details": {
    "active": {}
  }
}

Update settings 

Updates Tax Settings parameters used in tax calculations. All parameters are editable but none can be removed once set.

Parameters

  • defaultsobject

    Default configuration to be used on Stripe Tax calculations.

  • head_officeobject

    The place where your business is located.

Returns

A Tax Settings object.

POST /v1/tax/settings
curl https://api.stripe.com/v1/tax/settings \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d "defaults[tax_behavior]"=inclusive \
  -d "defaults[tax_code]"=txcd_10000000 \
  -d "head_office[address][country]"=DE
Response
{
  "object": "tax.settings",
  "defaults": {
    "tax_behavior": "inclusive",
    "tax_code": "txcd_10000000"
  },
  "head_office": {
    "address": {
      "city": null,
      "country": "DE",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    }
  },
  "livemode": false,
  "status": "active",
  "status_details": {
    "active": {}
  }
}

Retrieve settings 

Retrieves Tax Settings for a merchant.

Parameters

No parameters.

Returns

A Tax Settings object.

GET /v1/tax/settings
curl https://api.stripe.com/v1/tax/settings \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"
Response
{
  "object": "tax.settings",
  "defaults": {
    "tax_behavior": null,
    "tax_code": "txcd_10000000"
  },
  "head_office": {
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": "CA"
    }
  },
  "livemode": false,
  "status": "active",
  "status_details": {
    "active": {}
  }
}

Verification Session 

A VerificationSession guides you through the process of collecting and verifying the identities of your users. It contains details about the type of verification, such as what verification check to perform. Only create one VerificationSession for each verification in your system.

A VerificationSession transitions through multiple statuses throughout its lifetime as it progresses through the verification flow. The VerificationSession contains the user’s verified data after verification checks are complete.

Related guide: The Verification Sessions API

Endpoints