Skip to main content
PUT
Store the account's billing address

Authorizations

Authorization
string
header
required

A Cognito access token, issued through the dashboard's own sign-up and sign-in pages (a backend-for-frontend; there is no Cognito Hosted UI) and sent as Authorization: Bearer <jwt>. Dashboard operations require this scheme and cannot be called with an API key, with no exception. GET /v1/usage and GET /v1/limits offered both schemes from 0.8.0; 0.8.1 withdrew that, because the control-plane API serves them alone and its authorizer has no API-key branch. An account_id supplied by the client is ignored; all reads/writes are scoped server-side to the authenticated account.

Body

application/json

The postal address a subscription is billed to, in Stripe's own address field names so that what this account stores and what a Checkout session collects are the same shape rather than two that have to be mapped.

Only line1, city and country are required, and that is a deliberate refusal to over-validate. A postal code is not universal (Ireland, Hong Kong and the UAE among others), and a state or province is meaningful in a minority of countries; requiring either would reject real addresses from real customers to gain nothing a payment processor has asked for. Stripe itself requires only the country.

line1
string
required
Required string length: 1 - 200
city
string
required
Required string length: 1 - 100
country
string
required

ISO 3166-1 alpha-2, upper-case — the form Stripe stores and returns.

Pattern: ^[A-Z]{2}$
name
string

Who the invoice is addressed to, when that is not the account holder's own name.

Required string length: 1 - 100
line2
string
Required string length: 1 - 200
state
string

State, province, or region, where the country has them.

Required string length: 1 - 100
postal_code
string
Required string length: 1 - 20

Response

The address as it is now stored.

The stored billing address, or null when this account has never saved one. null rather than a 404: an account with no address is not a missing resource, it is an account whose settings form has an empty section, and answering 404 would make the page treat a normal state as an error.

address
required

The postal address a subscription is billed to, in Stripe's own address field names so that what this account stores and what a Checkout session collects are the same shape rather than two that have to be mapped.

Only line1, city and country are required, and that is a deliberate refusal to over-validate. A postal code is not universal (Ireland, Hong Kong and the UAE among others), and a state or province is meaningful in a minority of countries; requiring either would reject real addresses from real customers to gain nothing a payment processor has asked for. Stripe itself requires only the country.