Save the billing address

Overview

Set or change the billing address.

Use this when billing details change.

You'll need the address.

It's saved. A user has one billing address: the first call creates it and later calls replace it. The name on the address is taken from the user's profile.

With signup_business_id, when that signup business allows it, its location's phone, address, city and postal code are set to the same values.

Prerequisites

A bearer token. See Authentication.
The user's id (user_id), from List users.
A city_id, from List cities.

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

POST /api/v1/billing-address/save

Authentication

Partner or Account token

user_id must be a user inside your own account tree; otherwise 422.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Field	Type	Required	Notes
`user_id`	integer	Yes	The user the address is for. Must exist and be inside your account tree.
`company`	string	Yes	Company name on the bill. Up to 255 characters. Can't contain `<` or `>`.
`billing_email`	string	Yes	Billing email address. The domain must accept mail (it's checked with a DNS lookup), so test domains like `example.com` are rejected with `422`.
`mobile`	string	No	Billing phone number. Up to 20 characters.
`billing_address`	string	Yes	Street address. Up to 255 characters. Can't contain `<` or `>`.
`zipcode`	string	Yes	Postal code. 3 to 10 characters.
`city_id`	integer	Yes	The city. Must exist.
`signup_business_id`	integer	No	A signup business id. Must exist. When that signup business allows it, its location gets the same phone, address, city and postal code.

Request payload

{
  "user_id": 3011,
  "company": "Acme Corp",
  "billing_email": "<billing-email>",
  "mobile": "+15555550100",
  "billing_address": "123 Main St",
  "zipcode": "90210",
  "city_id": 456
}

Response body

The payload is inside data: the saved address. Field names here differ from Get the billing address.

Field	Type	Description
`id`	integer	The billing address id.
`user_id`	integer	The user the address belongs to.
`name`	string or null	The user's name, from their profile.
`email`	string	Billing email address (`billing_email`).
`phone`	string or null	Billing phone number (`mobile`).
`city_id`	integer	The city id.
`postal_code`	string	Postal code (`zipcode`).
`address`	string	Street address (`billing_address`).
`company_name`	string	Company name on the bill (`company`).
`created_at`	string	When the address was first saved.
`updated_at`	string	When the address was last saved.

Response payload

{
  "data": {
    "user_id": 3011,
    "name": "Jane Smith",
    "email": "<billing-email>",
    "phone": "+15555550100",
    "city_id": 456,
    "postal_code": "90210",
    "address": "123 Main St",
    "company_name": "Acme Corp",
    "updated_at": "2026-06-16T10:42:44.000000Z",
    "created_at": "2026-06-16T10:42:44.000000Z",
    "id": 1
  }
}

Examples

Success payload

See Response payload.

Error payload

422 Required fields missing

{
  "message": "The user id field is required. (and 5 more errors)",
  "errors": {
    "user_id": [
      "The user id field is required."
    ],
    "company": [
      "The company field is required."
    ],
    "billing_email": [
      "The billing email field is required."
    ],
    "billing_address": [
      "The billing address field is required."
    ],
    "zipcode": [
      "The zipcode field is required."
    ],
    "city_id": [
      "The city id field is required."
    ]
  }
}

422 Email rejected, unknown city

{
  "message": "The billing email field must be a valid email address. (and 1 more error)",
  "errors": {
    "billing_email": [
      "The billing email field must be a valid email address."
    ],
    "city_id": [
      "The selected city id is invalid."
    ]
  }
}

Status	Meaning
`200`	The address was saved.
`401`	The token is missing, expired or invalid.
`422`	A field is missing or invalid, the email is rejected, or `user_id` is outside your tree.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/billing-address/save" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"user_id": 3011, "company": "Acme Corp", "billing_email": "<billing-email>", "mobile": "+15555550100", "billing_address": "123 Main St", "zipcode": "90210", "city_id": 456}'