# Addresses Store billing and shipping addresses tied to a customer. Use them to pre-fill checkout flows, satisfy card network requirements on cross-border transactions, and keep tax-relevant data on record. Every endpoint requires a secret key (`sk_`). Addresses are scoped to the organization that owns the key. *** ## The address object Rebill auto-generates this on creation. Prefixed with `addr_`. The customer this address belongs to. Prefixed with `cus_`. Rebill omits this field when the address isn't linked to a customer (for example, a card billing address created at tokenization). Either `billing` or `shipping`. Two-letter country code you provided on creation. Rebill stores the value verbatim — it does not validate against ISO 3166-1 or a supported-country list. State or province. Pass the full name — Rebill doesn't normalize abbreviations. City name. Postal or ZIP code. Format depends on the country. Primary street line — number and street name. Secondary line — apartment, suite, floor, or reference. Rebill omits this field when not set. ```json { "id": "addr_12aa31cdfb574e4191e96e67523a3560", "customerId": "cus_786176c9d39f40d8af98428edb2aa3db", "type": "billing", "country": "AR", "state": "Buenos Aires", "city": "Buenos Aires", "zipCode": "1043", "lineOne": "Av. Corrientes 1234", "lineTwo": "Piso 5, Depto A" } ``` *** ## Create an address Attaches a new address to an existing customer. Create the customer first via the [Customers API](/api/reference/customers) if it doesn't exist yet — Rebill rejects addresses pointing to unknown customers. ### Request body Existing customer ID. Must match `cus_` + 32 hex chars (or `test_cus_` + 32 hex chars in sandbox). Two-letter country code. Rebill stores it as-is without validation. State or province. City name. Postal or ZIP code. Primary street line — number and street name. Secondary line — apartment, suite, floor, or reference. Either `billing` or `shipping`. Defaults to `billing` when omitted. ### Response `201 Created` with `{ "address": { ... } }`. ### Errors | Status | Cause | Usually happens when | | ------------------ | ------------------------------ | ---------------------------------------------------------------------- | | `400 Bad Request` | Invalid `customerId` format | You passed a raw UUID instead of a prefixed `cus_` ID | | `400 Bad Request` | Invalid `type` value | You passed anything other than `billing` or `shipping` | | `400 Bad Request` | Missing required field | `country`, `state`, `city`, `zipCode`, or `lineOne` wasn't in the body | | `401 Unauthorized` | Missing or invalid `x-api-key` | You forgot the header, or the key was rotated | | `404 Not Found` | Customer doesn't exist | The `customerId` doesn't match a customer in your organization | A customer can own multiple addresses of the same type. Rebill doesn't enforce uniqueness or a "default" address — your application decides which one to use at checkout. ```json { "address": { "id": "addr_12aa31cdfb574e4191e96e67523a3560", "customerId": "cus_786176c9d39f40d8af98428edb2aa3db", "type": "billing", "country": "AR", "state": "Buenos Aires", "city": "Buenos Aires", "zipCode": "1043", "lineOne": "Av. Corrientes 1234", "lineTwo": "Piso 5, Depto A" } } ``` *** ## Retrieve an address Fetches a single address by ID. Use it to verify the address on record before pre-filling a checkout form or to audit what a customer stored. ### Path parameters The address ID. Prefixed with `addr_`. ### Response `200 OK` with `{ "address": { ... } }`. ### Errors | Status | Cause | Usually happens when | | ------------------ | ------------------------------ | ---------------------------------------------------------------- | | `401 Unauthorized` | Missing or invalid `x-api-key` | | | `404 Not Found` | No address with that ID exists | The ID was deleted, mistyped, or belongs to another organization | ```json { "address": { "id": "addr_12aa31cdfb574e4191e96e67523a3560", "customerId": "cus_786176c9d39f40d8af98428edb2aa3db", "type": "billing", "country": "AR", "state": "Buenos Aires", "city": "Buenos Aires", "zipCode": "1043", "lineOne": "Av. Corrientes 1234", "lineTwo": "Piso 5, Depto A" } } ``` *** ## List addresses Returns every address in your organization. Most of the time you'll want to filter by customer via the `customerId` query parameter — useful for showing a customer's saved addresses at checkout. ### Query parameters Return only addresses belonging to this customer. Prefixed with `cus_`. ### Response `200 OK` with `{ "addresses": [ ... ] }`. Empty array if no addresses match. ### Errors | Status | Cause | Usually happens when | | ------------------ | ------------------------------ | -------------------- | | `401 Unauthorized` | Missing or invalid `x-api-key` | | ```json { "addresses": [ { "id": "addr_12aa31cdfb574e4191e96e67523a3560", "customerId": "cus_786176c9d39f40d8af98428edb2aa3db", "type": "billing", "country": "AR", "state": "Buenos Aires", "city": "Buenos Aires", "zipCode": "1043", "lineOne": "Av. Corrientes 1234", "lineTwo": "Piso 5, Depto A" }, { "id": "addr_2a94dfaf407c4f84a41578aad0a6122b", "customerId": "cus_786176c9d39f40d8af98428edb2aa3db", "type": "shipping", "country": "AR", "state": "Buenos Aires", "city": "Buenos Aires", "zipCode": "1414", "lineOne": "El Salvador 5678" } ] } ``` *** ## Update an address Updates any subset of fields on an existing address. Omitted fields stay unchanged. The `customerId` is fixed at creation. To move an address to a different customer, delete it and create a new one under the target customer. ### Path parameters The address ID. Prefixed with `addr_`. ### Request body Any field from [the address object](#the-address-object) except `customerId`. All fields are optional — include only the ones you want to change. ### Response `200 OK` with `{ "address": { ... } }` containing the full updated address. ### Errors | Status | Cause | Usually happens when | | ------------------ | ------------------------------ | ---------------------------------------------------------------- | | `400 Bad Request` | Invalid `type` value | You passed anything other than `billing` or `shipping` | | `401 Unauthorized` | Missing or invalid `x-api-key` | | | `404 Not Found` | No address with that ID exists | The ID was deleted, mistyped, or belongs to another organization | ```json { "address": { "id": "addr_12aa31cdfb574e4191e96e67523a3560", "customerId": "cus_786176c9d39f40d8af98428edb2aa3db", "type": "billing", "country": "AR", "state": "Buenos Aires", "city": "Buenos Aires", "zipCode": "1043", "lineOne": "Av. Cordoba 5678", "lineTwo": "Office 12" } } ``` *** ## Delete an address Permanently removes an address. Use it when a customer updates their billing info and you want to clean up the stale record. The customer and their other addresses stay intact. This action can't be undone. ### Path parameters The address ID. Prefixed with `addr_`. ### Response `200 OK` with an empty body. ### Errors | Status | Cause | Usually happens when | | ------------------ | ------------------------------ | ------------------------------------------------------------------------- | | `401 Unauthorized` | Missing or invalid `x-api-key` | | | `404 Not Found` | No address with that ID exists | The address was already deleted or the ID belongs to another organization |