> ## Documentation Index
> Fetch the complete documentation index at: https://docs.momentco.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Operations

> Common Billing API request and response examples

## Update a customer balance

Use this to refresh what a customer owes at the start of a new billing cycle. Send the new `balance` value in minor units. The request replaces the existing balance on the customer. A positive value represents an amount owed by the customer; a negative value represents a credit balance.

```bash theme={"system"}
curl -X PATCH https://api.momentpay.net/billing/customers/bcus_H4jp6KnU5cPw263v1jyz4 \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "balance": 5000
  }'
```

The response returns the full updated customer record with the new `balance` reflected.

```json theme={"system"}
{
  "id": "bcus_H4jp6KnU5cPw263v1jyz4",
  "external_reference": "UCR1234567890",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "currency": "ZAR",
  "balance": 5000
}
```

***

## Update an account balance

Use this to refresh the balance on a specific account within a customer. Send the new `balance` value in minor units. Only the targeted account is affected; other accounts under the same customer are unchanged. A positive value represents an amount owed; a negative value represents a credit on the account.

```bash theme={"system"}
curl -X PATCH https://api.momentpay.net/billing/accounts/bacc_H4jp6KnU5cPw263v1jyz4 \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "balance": 10000
  }'
```

The response returns the full updated account record with the new `balance` reflected.

```json theme={"system"}
{
  "id": "bacc_H4jp6KnU5cPw263v1jyz4",
  "external_reference": "UAR1234567890",
  "customer_id": "bcus_H4jp6KnU5cPw263v1jyz4",
  "name": "Subscription Account",
  "currency": "ZAR",
  "balance": 10000
}
```

***

## Update a bill

Use this to record a partial or full payment against a bill outside of the webhook flow. Send the `amount_paid` value in minor units. Moment recalculates `amount_remaining` automatically and updates `status` to `paid` if the bill is fully settled.

```bash theme={"system"}
curl -X PATCH https://api.momentpay.net/billing/bills/bill_H4jp6KnU5cPw263v1jyz4 \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_paid": 1500
  }'
```

The response returns the full updated bill record. In this example a partial payment of 1500 has been applied against an `amount_due` of 2000, leaving `amount_remaining` of 500 and a status of `unpaid`.

```json theme={"system"}
{
  "id": "bill_H4jp6KnU5cPw263v1jyz4",
  "external_reference": "UBR1234567890",
  "customer_id": "bcus_H4jp6KnU5cPw263v1jyz4",
  "account_id": "bacc_H4jp6KnU5cPw263v1jyz4",
  "status": "unpaid",
  "currency": "ZAR",
  "amount_due": 2000,
  "amount_paid": 1500,
  "amount_remaining": 500,
  "bill_date": "2025-01-01",
  "due_date": "2025-01-31"
}
```

<Note>
  In a webhook-driven integration, `amount_paid` is updated automatically when Moment receives a payment and sends an `obligation.amount_applied` event. Use this endpoint for manual reconciliation or corrections.
</Note>