Customer Billing
Reference for the customer_billing resource. Requests follow the conventions in
Requests and Responses; fields you
receive and may write are filtered by your user's permissions, so responses can
contain a subset of the fields below.
Operations
| Operation | Request |
|---|---|
| List | GET /{profile}/user/v4/customer_billing |
| Fetch | GET /{profile}/user/v4/customer_billing/{id} |
| Create | POST /{profile}/user/v4/customer_billing |
| Update | PATCH /{profile}/user/v4/customer_billing/{id} |
| Delete | DELETE /{profile}/user/v4/customer_billing/{id} |
Required on create: link customer under data.relationships — a create that omits it is rejected with 422 naming the relationship.
How it works
customer_billing is a customer's billing method — a billing address + schedule plus a
payment method that is either a credit card OR a bank/ACH account, selected by bill_type_id
(1 = credit card, 2 = bank/ACH, 3 = manual/none). Full CRUD plus a list endpoint.
A row belongs to a customer through customer_id, and its permission location is that customer's:
everything is gated by the Customer Billing permission at the customer's location (leads use
the lead-billing permission).
Security — card & bank numbers are masked
bill_cc_number and bill_bank_number are encrypted at rest and returned masked (last 4,
e.g. xxxxxxxxxxxx1111) on every read — you cannot read a full card or account number back through
the API. The payment method is not exposed to the AI/MCP surfaces at all.
Creating
POST /customer_billing requires the customer parent (in data.relationships) and
bill_type_id, then the fields for that payment type:
| Field | Required | Notes |
|---|---|---|
bill_type_id |
Yes | 1 credit card, 2 bank/ACH, 3 manual. Write-once — cannot be changed after create. |
Credit card (bill_type_id: 1):
| Field | Required | Notes |
|---|---|---|
bill_cc_type |
Yes | Visa | MasterCard | Discover | American Express | Other. |
bill_cc_name |
Yes | Name on card. |
bill_cc_number |
Yes | Digits only; validated against the declared bill_cc_type. Write-once — settable on create, then read-only (masked). |
bill_cc_expiration |
Yes | 4 digits, MMYY. |
Bank/ACH (bill_type_id: 2):
| Field | Required | Notes |
|---|---|---|
bill_bank_type |
Yes | Checking | Savings | Other. |
bill_bank_name |
Yes | Bank name. |
bill_bank_number |
No | Account number (digits); returned masked. |
bill_bank_route |
No | Must be a valid ABA routing number when present. |
bill_bank_institution_number |
No | Digits when present. |
Optional on any type: bill_address_same, bill_address1/2, bill_city, bill_state,
bill_zip, bill_phone, bill_cycle_id, bill_day_of_month, bill_start_date, bill_comment,
bill_nickname, bill_ach. Free-text fields (bill_nickname, bill_comment, addresses) must not
contain card data.
curl -X POST "https://portal.securitytrax.com/acme/user/v4/customer_billing" \
-H "Authorization: Bearer stx_acme_..." \
-H "Content-Type: application/json" \
-d '{"data":{"attributes":{"bill_type_id":1,"bill_cc_type":"Visa","bill_cc_name":"John Doe","bill_cc_number":"4111111111111111","bill_cc_expiration":"1230"},"relationships":{"customer":{"data":{"type":"customers","id":100}}}}}'
Updating
PATCH /customer_billing/{id} updates the billing address/schedule and (for bank) the bank
details. bill_type_id and bill_cc_number are write-once — a PATCH that sends either
returns 422. To change a card, delete the billing and create a new one.
Deleting
DELETE /customer_billing/{id} soft-deletes the billing method. A billing that backs an active
recurring invoice, or an invoice with a future amount still due, cannot be deleted (422).
Not supported here (portal-only)
The billing form's use_default address auto-fill, duplicate-card/bank detection, BIN-type
blocking, billing-uses assignment, and "set as default billing" are SecurityTrax-UI conveniences and are
not part of this API — send explicit values.
Listing
GET /customer_billing returns active billings at locations where you can view customer billing.
Filters: customer_id, bill_type_id, bill_cycle_id, created_at_from/_to,
updated_at_from/_to. Sortable: id, customer_id, bill_type_id, created_at, updated_at.
Add ?count_only=true for just the total.
Fields
Fields are grouped by the permission that gates them. A group you may not view
is absent from responses; a group you may not write is rejected with 422 when
sent in a write.
Billing
View: customers — Customer Billing at the record's location; leads — Lead Billing. Create: customers — Customer Billing at the record's location; leads — Lead Billing. Update: customers — Customer Billing at the record's location; leads — Lead Billing.
| Field | Type | Writable | Validation |
|---|---|---|---|
customer_id |
integer (nullable) | Create, update | min 0 |
bill_address_same |
boolean (nullable) | Create, update | — |
bill_address1 |
string (nullable) | Create, update | max length 255 |
bill_address2 |
string (nullable) | Create, update | max length 255 |
bill_city |
string (nullable) | Create, update | max length 150 |
bill_state |
string (nullable) | Create, update | max length 2 |
bill_zip |
string (nullable) | Create, update | max length 11 |
bill_phone |
string (nullable) | Create, update | max length 15 |
bill_cycle_id |
integer (nullable) | Create, update | min 0 |
bill_day_of_month |
integer (nullable) | Create, update | min 0 |
bill_start_date |
string (nullable) | Create, update | — |
bill_type_id |
integer (nullable) | Create only | min 0 |
bill_comment |
string (nullable) | Create, update | max length 100 |
bill_nickname |
string (nullable) | Create, update | max length 100 |
status |
string (nullable) | Read-only | one of: active, deleted |
Payment Method
View: customers — Customer Billing at the record's location; leads — Lead Billing. Create: customers — Customer Billing at the record's location; leads — Lead Billing. Update: customers — Customer Billing at the record's location; leads — Lead Billing.
| Field | Type | Writable | Validation |
|---|---|---|---|
bill_cc_type |
string (nullable) | Create, update | one of: Visa, MasterCard, Discover, American Express, Other |
bill_cc_name |
string (nullable) | Create, update | max length 100 |
bill_cc_number |
string (nullable) | Create only | — |
bill_cc_expiration |
string (nullable) | Create, update | max length 15 |
bill_bank_type |
string (nullable) | Create, update | one of: Checking, Savings, Other |
bill_bank_name |
string (nullable) | Create, update | max length 150 |
bill_bank_institution_number |
string (nullable) | Create, update | max length 150 |
bill_bank_number |
string (nullable) | Create, update | — |
bill_bank_route |
string (nullable) | Create, update | max length 50 |
bill_ach |
boolean (nullable) | Create, update | — |
Pagination
The list endpoint uses client-controlled offset pagination: ?page= (1-based) and
?per_page= (default 25, max 100). The response mirrors
meta.pagination (page, per_page, total, last_page) and sends an RFC5988
Link header; follow rel="next" to walk pages. See
Pagination.
Filters
The list endpoint accepts these query-param filters: customer_id, bill_type_id, bill_cycle_id, created_at_from, created_at_to, updated_at_from, updated_at_to.
An unsupported filter parameter returns 422. See
Filtering collections
for matching semantics.
Sorting
GET .../customer_billing?sort= orders the list by: id, customer_id, bill_type_id, created_at, updated_at.
Prefix a field with - for descending; comma-separate for tie-breakers. An
unsupported field returns 422. See
Sorting collections.
Related
- Requests and Responses — envelope, errors, pagination, and rate limits.
- Authentication — tokens and the
Authorizationheader.