---
title: "Create an agreement for recurring payments"
method: POST
path: "/v1/agreements"
tags: ["Agreements"]
---

# Create an agreement for recurring payments

`POST /v1/agreements`

You can use this endpoint to create a new agreement.

## Request body

- CreateAgreementRequest — The Agreement Request Payload
  - `description` string — A human-readable description of the purpose of the agreement for recurring payments. We’ll show the description to your user when they make their first payment to activate this agreement. Limited to 255 characters.
  - `reference` string — Associate a reference with this agreement to help you identify it. Limited to 255 characters.
  - `user_identifier` string — Associate an identifier with the user who will enter into this agreement with your service.user_identifier is not unique – multiple agreements can have identical user_identifier values.You should not include personal data in user_identifier.

## Response `201`

Created

- Agreement — Contains information about a user's agreement for recurring payments. An agreement represents an understanding between you and your paying user that you'll use their card to make ongoing payments for a service.
  - `agreement_id` string — The unique ID GOV.UK Pay automatically associated with this agreement when you created it.
  - `cancelled_date` string — The date and time this agreement was cancelled. This value uses Coordinated Universal Time (UTC) and ISO 8601 format – `YYYY-MM-DDThh:mm:ss.sssZ`.
  - `created_date` string — The date and time you created this agreement. This value uses Coordinated Universal Time (UTC) and ISO 8601 format – `YYYY-MM-DDThh:mm:ss.sssZ`.
  - `description` string — The description you sent when creating this agreement.
  - `payment_instrument` PaymentInstrument
    - `CardDetails` CardDetailsFromResponse
      - `billing_address` Address — A structure representing the billing address of a card
        - `city` string — The paying user's city.
        - `country` string — The paying user’s country, displayed as a 2-character ISO-3166-1-alpha-2 code.
        - `line1` string — The first line of the paying user’s address.
        - `line2` string — The second line of the paying user’s address.
        - `postcode` string — The paying user's postcode.
      - `card_brand` string
      - `card_type` string
      - `cardholder_name` string
      - `expiry_date` string
      - `first_digits_card_number` string
      - `last_digits_card_number` string
    - `created_date` string — The date and time you created this payment instrument. This value uses Coordinated Universal Time (UTC) and ISO 8601 format – `YYYY-MM-DDThh:mm:ss.sssZ`.
    - `type` 'card' — The type of payment instrument.
  - `reference` string — The reference you sent when creating this agreement.
  - `status` 'created' | 'active' | 'cancelled' | 'inactive' — The status of this agreement. You can [read more about the meanings of each agreement status.](https://docs.payments.service.gov.uk/recurring_payments/#understanding-agreement-status)
  - `user_identifier` string — The identifier you sent when creating this agreement. `user_identifier` helps you identify users in your records.

## Other responses

- `400` — Bad request
- `401` — Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)
- `422` — Your request failed. Check the `code` and `description` in the response to find out why your request failed.
- `429` — Too many requests
- `500` — Downstream system error

---

[API](https://skmtc.net/government-digital-service/apis/gov-uk-pay-api.md) · [All operations](https://skmtc.net/government-digital-service/apis/gov-uk-pay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/government-digital-service/gov-uk-pay-api/revisions/4dc2d80f453a/schema)