Customer Payables

Reference for the customer_payables 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

Not available as a standard REST operation for this resource: create — such requests return 402 feature_not_enabled or 403 permission_denied (see the actions above for this resource's write path).

Required on create: link customer under data.relationships — a create that omits it is rejected with 422 naming the relationship.

How it works

A customer_payables record is a payroll/commission amount owed to a payee, tied to a customer. Gated by Customer Payables at the customer's location.

Payables are generated by the payroll engine, not created field-by-field. The payee, role, entity, and calculation fields are engine-assigned and read-only. A payable's amount is the sum of its line items (customer_payable_line_items) and is not directly writable.

You can read payables, edit a small set of fields (PATCH), and remove one (DELETE, a soft-delete). There is no plain create — a payable comes into being through the generate action below.

Generating a payable

POST /customer_payables/generate runs the payroll engine to scaffold a pending payable and its line items for a payee. You then edit the line amounts (customer_payable_line_items) and activate the payable by PATCHing status: active.

curl -X POST "https://portal.securitytrax.com/acme/user/v4/customer_payables/generate" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"customer_id":100,"payroll_role_function_id":12,"payroll_entity_id":45}}}'

Returns the pending payable (201). Requires Customer Payables at the customer's location and a company with payroll configured; a company with no payroll setup returns 409, and an invalid payee/role-function returns 422.

curl -X PATCH "https://portal.securitytrax.com/acme/user/v4/customer_payables/42" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"payroll_payment_status_id":2,"expected_pay_date":"2026-08-01","notes":"Approved"}}}'

Removing a payable

DELETE /customer_payables/{id} soft-deletes a payable (it stops appearing in reads; the row is retained). Gated by Customer Payables at the customer's location.

curl -X DELETE "https://portal.securitytrax.com/acme/user/v4/customer_payables/42" \
  -H "Authorization: Bearer stx_acme_..."

Reading payables

GET /customer_payables?customer_id={customerId} lists a customer's payables (filters: customer_id, payroll_payment_status_id, payroll_role_function_id, created_at range; sort: id, customer_id, amount, expected_pay_date, created_at; ?count_only=true for the total). A customer's payables are also reachable via GET /customers/{id}?include=payables.

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.

Payable

View: customers — Customer Payables Info at the record's location; leads — Customer Lead Payables Info. Update: customers — Customer Payables Info at the record's location; leads — all of: the standard canModifyLead rules; Customer Lead Payables Info.

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, payroll_payment_status_id, payroll_role_function_id, created_at_from, created_at_to. An unsupported filter parameter returns 422. See Filtering collections for matching semantics.

Sorting

GET .../customer_payables?sort= orders the list by: id, customer_id, amount, expected_pay_date, created_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 Authorization header.