curl --request PUT \
--url https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/billing/address \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"line1": "1 Market Street",
"line2": "Floor 6",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
}
'import requests
url = "https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/billing/address"
payload = {
"line1": "1 Market Street",
"line2": "Floor 6",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
line1: '1 Market Street',
line2: 'Floor 6',
city: 'San Francisco',
state: 'CA',
postal_code: '94105',
country: 'US'
})
};
fetch('https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/billing/address', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/billing/address",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'line1' => '1 Market Street',
'line2' => 'Floor 6',
'city' => 'San Francisco',
'state' => 'CA',
'postal_code' => '94105',
'country' => 'US'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/billing/address"
payload := strings.NewReader("{\n \"line1\": \"1 Market Street\",\n \"line2\": \"Floor 6\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"postal_code\": \"94105\",\n \"country\": \"US\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/billing/address")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"line1\": \"1 Market Street\",\n \"line2\": \"Floor 6\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"postal_code\": \"94105\",\n \"country\": \"US\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/billing/address")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"line1\": \"1 Market Street\",\n \"line2\": \"Floor 6\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"postal_code\": \"94105\",\n \"country\": \"US\"\n}"
response = http.request(request)
puts response.read_body{
"address": {
"line1": "1 Market Street",
"line2": "Floor 6",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
}
}{
"error": {
"code": "invalid_request",
"type": "invalid_request",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"retryable": true
}
}{
"error": {
"code": "invalid_request",
"type": "invalid_request",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"retryable": true
}
}{
"error": {
"code": "invalid_request",
"type": "invalid_request",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"retryable": true
}
}{
"error": {
"code": "invalid_request",
"type": "invalid_request",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"retryable": true
}
}{
"error": {
"code": "invalid_request",
"type": "invalid_request",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"retryable": true
}
}Store the account's billing address
Replaces the stored billing address with the one sent. A whole address, not a patch: a partial update of a postal address is how a customer who moves from a country with states to one without ends up with a province that is no longer theirs.
What Stripe holds is collected separately, at Checkout, and applies to the invoice being paid. This is the account’s own record and what the settings form renders.
curl --request PUT \
--url https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/billing/address \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"line1": "1 Market Street",
"line2": "Floor 6",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
}
'import requests
url = "https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/billing/address"
payload = {
"line1": "1 Market Street",
"line2": "Floor 6",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
line1: '1 Market Street',
line2: 'Floor 6',
city: 'San Francisco',
state: 'CA',
postal_code: '94105',
country: 'US'
})
};
fetch('https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/billing/address', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/billing/address",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'line1' => '1 Market Street',
'line2' => 'Floor 6',
'city' => 'San Francisco',
'state' => 'CA',
'postal_code' => '94105',
'country' => 'US'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/billing/address"
payload := strings.NewReader("{\n \"line1\": \"1 Market Street\",\n \"line2\": \"Floor 6\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"postal_code\": \"94105\",\n \"country\": \"US\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/billing/address")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"line1\": \"1 Market Street\",\n \"line2\": \"Floor 6\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"postal_code\": \"94105\",\n \"country\": \"US\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/billing/address")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"line1\": \"1 Market Street\",\n \"line2\": \"Floor 6\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"postal_code\": \"94105\",\n \"country\": \"US\"\n}"
response = http.request(request)
puts response.read_body{
"address": {
"line1": "1 Market Street",
"line2": "Floor 6",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
}
}{
"error": {
"code": "invalid_request",
"type": "invalid_request",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"retryable": true
}
}{
"error": {
"code": "invalid_request",
"type": "invalid_request",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"retryable": true
}
}{
"error": {
"code": "invalid_request",
"type": "invalid_request",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"retryable": true
}
}{
"error": {
"code": "invalid_request",
"type": "invalid_request",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"retryable": true
}
}{
"error": {
"code": "invalid_request",
"type": "invalid_request",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"retryable": true
}
}Authorizations
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
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.
1 - 2001 - 100ISO 3166-1 alpha-2, upper-case — the form Stripe stores and returns.
^[A-Z]{2}$Who the invoice is addressed to, when that is not the account holder's own name.
1 - 1001 - 200State, province, or region, where the country has them.
1 - 1001 - 20Response
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.
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.
Show child attributes
Show child attributes

