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

# Payment Contracts API Overview

> Create and manage recurring payment arrangements against a saved payment method.

<Info>
  [← Back to API Reference](/api-reference/overview)
</Info>

A payment contract is a single recurring payment arrangement: one customer, one saved payment method, one schedule. Orchestra executes the payments for you and keeps track of how many have run.

Contracts are always created from a **payment schedule template**, which you configure once in the Orchestra portal. The template sets the rhythm (how often payments run and through which payment gateway account), and the contract supplies the specifics (who is paying, how much, from which token, starting when).

## Templates and Contracts

|                | Payment schedule template                             | Payment contract                            |
| -------------- | ----------------------------------------------------- | ------------------------------------------- |
| Where it lives | Orchestra portal                                      | REST API                                    |
| How many       | One per billing plan                                  | One per customer arrangement                |
| Defines        | Frequency and payment gateway account                 | Token, amount, currency, start date, limits |
| Example        | "Monthly subscription, billed through our EU gateway" | "Customer 4821, EUR 29.00, from 1 October"  |

One template typically backs many contracts. Reusing a template is what keeps a subscription plan consistent across all the customers on it.

## Contract Lifecycle

<Steps>
  <Step title="Active">
    Created and running. Orchestra charges the saved token on each due date and increments the occurrence count after each successful payment.
  </Step>

  <Step title="Paused">
    Temporarily stopped. No payments are attempted. The contract keeps its history and can be resumed.
  </Step>

  <Step title="Cancelled">
    Permanently stopped. A cancelled contract cannot be resumed; create a new contract instead.
  </Step>

  <Step title="Completed">
    Reached its end date or its maximum number of payments. No further action needed.
  </Step>
</Steps>

<Warning>
  Cancelling is final. If you only want to stop payments for a while, pause the contract instead.
</Warning>

## Ending a Contract

A contract can be open-ended, or you can bound it in either of two ways, or both:

* **`endDate`** stops payments after a calendar date.
* **`maxOccurrences`** stops payments after a set number of successful charges.

Whichever limit is reached first moves the contract to Completed.

## Endpoints

<CardGroup cols={2}>
  <Card title="List Contracts" icon="list" href="/api-reference/paymentcontract/list-payment-contracts">
    Page through your contracts, filtered by template or status.
  </Card>

  <Card title="Create Contract" icon="plus" href="/api-reference/paymentcontract/create-a-new-payment-contract">
    Start a recurring arrangement from a template.
  </Card>

  <Card title="Retrieve Contract" icon="magnifying-glass" href="/api-reference/paymentcontract/retrieve-payment-contract">
    Get the full detail of one contract, including its schedule and charge data.
  </Card>

  <Card title="Update Contract" icon="pen" href="/api-reference/paymentcontract/update-a-payment-contract">
    Change the name, end date, maximum occurrences or metadata.
  </Card>

  <Card title="Pause Contract" icon="pause" href="/api-reference/paymentcontract/pause-a-payment-contract">
    Stop payments temporarily, keeping the contract intact.
  </Card>

  <Card title="Resume Contract" icon="play" href="/api-reference/paymentcontract/resume-a-payment-contract">
    Restart a paused contract.
  </Card>

  <Card title="Cancel Contract" icon="ban" href="/api-reference/paymentcontract/cancel-a-payment-contract">
    Stop a contract permanently.
  </Card>

  <Card title="Scheduled Payments Guide" icon="book" href="/guides/rest-api/scheduled-payments">
    Worked examples, timezone handling and lifecycle detail.
  </Card>
</CardGroup>