# Collect contract payments automatically

Charge the default payment method for each contract invoice and monitor collection status.

Set the [collection_method](https://docs.stripe.com/api/v2/billing-contracts/contracts/create.md?api-version=2026-10-28.preview#v2_create_contracts-billing_settings-collection_settings_details-collection_method) for a [contract](https://docs.stripe.com/billing/contracts.md) to `charge_automatically` to have Stripe attempt payment on each contract invoice using the default payment method. Use this collection method when you want Stripe to collect each invoice without asking the customer to pay it.

## Before you begin 

You must have access to the contracts private preview. If you don’t have access, [sign up on the Contracts page](https://docs.stripe.com/billing/contracts.md).

[Attach a payment method to the customer](https://docs.stripe.com/api/payment_methods/attach.md), then set a default payment method on either the contract’s [billing_settings.billing_profile_details.default_payment_method](https://docs.stripe.com/api/v2/billing-contracts/contracts/create.md?api-version=2026-10-28.preview#v2_create_contracts-billing_settings-billing_profile_details-default_payment_method) or the customer’s [invoice_settings.default_payment_method](https://docs.stripe.com/api/customers/update.md#update_customer-invoice_settings-default_payment_method). The contract-level default payment method takes precedence over the customer’s. Contract payments don’t support cards that require mandates, so using one as the effective default payment method returns a validation error.

> Setting [billing_settings.bill_settings_details.invoice.time_until_due](https://docs.stripe.com/api/v2/billing-contracts/contracts/create.md?api-version=2026-10-28.preview#v2_create_contracts-billing_settings-bill_settings_details-invoice-time_until_due) with `charge_automatically` returns a validation error. These invoices have no payment term, because Stripe attempts payment as soon as we finalize the invoice.

## Create and activate the contract 

Set [billing_settings.collection_settings_details.collection_method](https://docs.stripe.com/api/v2/billing-contracts/contracts/create.md?api-version=2026-10-28.preview#v2_create_contracts-billing_settings-collection_settings_details-collection_method) to `charge_automatically` and set the default payment method in [billing_settings.billing_profile_details.default_payment_method](https://docs.stripe.com/api/v2/billing-contracts/contracts/create.md?api-version=2026-10-28.preview#v2_create_contracts-billing_settings-billing_profile_details-default_payment_method):

```curl
curl -X POST https://api.stripe.com/v2/billing/contracts \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-10-28.preview" \
  --json '{
    "currency": "usd",
    "contract_number": "C-2026-0300",
    "terms": [
        {
            "type": "recurring_price",
            "recurring_price": {
                "price": "{{PRICE_ID}}",
                "starts_at": {
                    "type": "timestamp",
                    "timestamp": "2026-09-01T00:00:00Z"
                },
                "ends_at": {
                    "type": "timestamp",
                    "timestamp": "2027-09-01T00:00:00Z"
                }
            }
        }
    ],
    "billing_settings": {
        "billing_profile_details": {
            "customer": "{{CUSTOMER_ID}}",
            "default_payment_method": "{{PAYMENT_METHOD_ID}}"
        },
        "collection_settings_details": {
            "collection_method": "charge_automatically"
        }
    }
  }'
```

When you [activate the contract](https://docs.stripe.com/api/v2/billing-contracts/contracts/activate.md?api-version=2026-10-28.preview), Stripe finalizes the first invoice (when applicable) and attempts payment. The contract becomes `active` even if the payment is processing or fails, and Stripe never rolls back an activation or an update after a payment failure. The same applies to invoices created by an immediate contract update.

Some payment methods, such as ACH Direct Debit, complete asynchronously and can take several days. The contract stays active while the payment processes, so decide whether to provision service immediately or wait for the invoice to be paid.

## Monitor collection status 

A contract’s `collection_status` summarizes collection across its invoices. It’s separate from the contract’s lifecycle [status](https://docs.stripe.com/api/v2/billing-contracts/contracts/object.md?api-version=2026-10-28.preview#v2_contract_object-status). A failed payment or a transition to `unpaid` doesn’t cancel an active contract or suspend your customer’s access to your service. Your integration controls access.

| Collection status | Meaning | Recommended action |
| --- | --- | --- |
| `current` | No invoices currently require collection recovery. Invoices can still be in draft or awaiting their first payment attempt. For `send_invoice`, an open invoice is `current` until its due date passes, even if a payment is processing or has failed. | Continue service according to your policy. If you require successful payment before providing access, check the individual invoices. |
| `past_due` | At least one automatically charged invoice has a declined, processing, or authentication-pending payment, or a sent invoice has passed its due date. The invoice hasn’t reached its unpaid deadline. | Treat this as a grace period. Monitor processing payments, and help the customer resolve failed payments or complete authentication. |
| `unpaid` | At least one outstanding invoice has reached the unpaid deadline described below. New cycle invoices stay in draft for both collection methods. See [Handle recurring invoices while unpaid](https://docs.stripe.com/billing/contracts/automatic-collection.md#invoices-while-unpaid) for recovery behavior. | Suspend service according to your agreement with the customer. Review outstanding invoices to decide how to recover payment. |
| `blocked` | Stripe couldn’t finalize an invoice, so collection requires your intervention. | [List the contract’s invoices](https://docs.stripe.com/billing/contracts.md#list-invoices-for-a-contract), find the draft invoice, inspect its [last_finalization_error](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error), and fix the underlying problem. Then finalize or delete that invoice. |

If invoices qualify for different statuses, Stripe uses this order: `unpaid`, `blocked`, `past_due`, then `current`. For example, a finalization failure on a newer invoice doesn’t clear an older invoice’s `unpaid` status.

Stripe evaluates each invoice using its collection method:

- **`charge_automatically`**: A declined payment, processing payment, or payment awaiting customer authentication (such as 3D Secure) makes the contract `past_due`. This includes asynchronous payments that take several days to process. The contract becomes `unpaid` when an invoice still has an unresolved payment 15 days after finalization. Exhausting payment retries doesn’t make the contract `unpaid` before that deadline. The deadline applies to failed, processing, and authentication-pending payments. It’s measured from invoice finalization, so another payment attempt doesn’t restart it. An invoice awaiting its first payment attempt remains `current`; a temporary payment error can also leave it `current` before the deadline.
- **`send_invoice`**: An outstanding invoice makes the contract `past_due` after its due date, and `unpaid` 30 days after that due date. Payments that are processing or failed before the due date don’t make the contract `past_due`. The 30-day period starts at the invoice’s due date, not its creation or finalization date.

The 15-day and 30-day deadlines aren’t configurable. A transition to `unpaid` doesn’t itself stop collection on existing invoices or cancel a payment that’s processing. An invoice that’s paid, voided, or marked uncollectible no longer keeps the contract `past_due` or `unpaid`, but other invoices can still require payment. Check the contract’s updated status after resolving an invoice. A return to `current` doesn’t necessarily mean every invoice was paid.

Subscribe to these events to respond when the contract’s collection status changes:

- `v2.billing.contract.collection_current`
- `v2.billing.contract.collection_past_due`
- `v2.billing.contract.collection_unpaid`
- `v2.billing.contract.collection_blocked`

## Monitor payments 

Also subscribe to these invoice events to monitor individual payment attempts. A contract can have multiple outstanding invoices, so a payment event doesn’t necessarily change its collection status:

- [invoice.payment_action_required](https://docs.stripe.com/api/events/types.md#event_types-invoice.payment_action_required): Send the customer to complete authentication.
- [invoice.payment_succeeded](https://docs.stripe.com/api/events/types.md#event_types-invoice.payment_succeeded): Confirm that a payment attempt succeeded.
- [invoice.payment_failed](https://docs.stripe.com/api/events/types.md#event_types-invoice.payment_failed): Notify the customer and provide a way to retry the payment.

## Recover a failed payment 

When you receive `invoice.payment_failed` or `v2.billing.contract.collection_past_due`:

1. [List the contract’s invoices](https://docs.stripe.com/billing/contracts.md#list-invoices-for-a-contract) and identify which need attention. A `past_due` contract can have a payment that’s still processing, so check the invoice before asking the customer to retry.
2. For an invoice that’s overdue, has a failed payment, or requires authentication, send the customer its [hosted_invoice_url](https://docs.stripe.com/api/invoices/object.md#invoice_object-hosted_invoice_url). The [hosted invoice page](https://docs.stripe.com/invoicing/hosted-invoice-page.md) lets them complete payment or use another payment method.
3. Apply your grace-period policy while the contract is `past_due`. If you receive `v2.billing.contract.collection_unpaid`, suspend service according to your agreement with the customer. Cancel the contract separately if your policy requires it.
4. Use `v2.billing.contract.collection_current` to reevaluate access after recovery. If your policy requires successful payment before restoring access, also confirm that the required invoices were paid, because voiding or marking an invoice uncollectible can also clear its collection status.

## Handle recurring invoices while unpaid 

For both `charge_automatically` and `send_invoice`, when a contract has a `collection_status` of `unpaid`, Stripe continues creating invoices each billing cycle but sets `auto_advance` to `false` on new invoices. These invoices stay in `draft`: Stripe doesn’t automatically finalize them, send them to the customer, or attempt payment.

When the contract is no longer `unpaid`, new cycle invoices are created with `auto_advance=true` and follow normal finalization and collection for the selected collection method. Invoices created while the contract was `unpaid` keep `auto_advance=false` and stay in draft. Review these invoices separately and [turn on automatic advancement](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection.md#update-auto) for any you decide to collect.

## Test automatic collection 

Combine [test clocks](https://docs.stripe.com/billing/testing.md#test-clocks) with [test payment methods](https://docs.stripe.com/testing.md#declined-payments) to simulate successful, failed, and asynchronous payments. Confirm that your integration handles each collection status and invoice payment event, including:

- Processing payments and payments awaiting authentication entering `past_due`.
- Exhausted retries remaining `past_due` until the 15-day deadline.
- Unresolved payments becoming `unpaid` 15 days after invoice finalization.
- For `send_invoice`, outstanding invoices becoming `past_due` after their due date and `unpaid` 30 days later.
- An invoice being paid, voided, or marked uncollectible while another invoice still requires payment.
- New cycle invoices staying in draft with `auto_advance=false` while a contract is `unpaid`, for both collection methods.
- New invoices advancing normally after recovery, while invoices created during the `unpaid` period stay in draft.
- An unpaid invoice taking precedence over a finalization failure on another invoice.
- Your policy for provisioning, suspending, and restoring service as collection status changes.
