---
title: "Partially update subscription"
method: PATCH
path: "/processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}"
tags: ["Subscriptions"]
---

# Partially update subscription

`PATCH /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}`

Use this method to partially update a subscription. Structure your request to follow the [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) standard.  

To update a subscription, you need its subscriptionId, which you sent in the request of the [Create subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/create) method.  

**Note:** If you don't have the subscriptionId, use our [List subscriptions](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/list) method to search for the payment.  

You can update all of the properties of the subscription except for the following:  

**Can't delete**  
- recurringOrder
- description
- name

**Can't perform any PATCH operation**  
- currentState
- type
- frequency
- paymentPlan

## Path parameters

- `processingTerminalId` string, required
- `subscriptionId` string, required

## Headers

- `Authorization` string, required
- `Idempotency-Key` string, uuid, required

## Request body

- PatchDocument[] — A JSON Patch document as defined by RFC 6902.
  - union — A JSON Patch operation as defined by RFC 6902.
    - object — A Patch Add Operation.
      - `op` 'add', required — Discriminator value: add
      - `path` string, required — Location where you want to add the value. The format for this value is JSON Pointer.
      - `value` unknown, required
    - object — A Patch Remove Operation.
      - `op` 'remove', required — Discriminator value: remove
      - `path` string, required — Location of the value that you want to remove. The format for this value is JSON Pointer.
    - object — A Patch Replace Operation.
      - `op` 'replace', required — Discriminator value: replace
      - `path` string, required — Location of the value that you want to replace. The format for this value is JSON Pointer.
      - `value` unknown, required
    - object — A Patch Move Operation.
      - `op` 'move', required — Discriminator value: move
      - `from` string, required — Location of the value that you want to move. The format for this value is JSON Pointer.
      - `path` string, required — Location where you want to move the value to. The format for this value is JSON Pointer.
    - object — A Patch Copy Operation.
      - `op` 'copy', required — Discriminator value: copy
      - `from` string, required — Location of the value that you want to copy. The format for this value is JSON Pointer.
      - `path` string, required — Location where you want to copy the value to. The format for this value is JSON Pointer.
    - object — A Patch Test Operation.
      - `op` 'test', required — Discriminator value: test
      - `path` string, required — Location of the value that you want to test. The format for this value is JSON Pointer.
      - `value` unknown, required

## Response `200`

Successful request. We have updated the subscription.

- Subscription
  - `subscriptionId` string, required — Unique identifier that the merchant assigned to the subscription.
  - `processingTerminalId` string, required — Unique identifier of the terminal that the subscription is linked to.
  - `paymentPlan` PaymentPlanSummary, required
    - `paymentPlanId` string, required — Unique identifier that the merchant assigns to the payment plan.
    - `name` string, required — Name of the payment plan.
    - `link` Link — Object that contains HATEOAS links for the resource.
      - `rel` string, required — Indicates the relationship between the current resource and the target resource.
      - `method` string, required — HTTP method that you need to use with the target resource.
      - `href` string, required — URL of the target resource.
  - `secureToken` SecureTokenSummary, required — Object that contains information about the secure token.
    - `secureTokenId` string, required — Unique identifier that the merchant assigned to the secure token.
    - `customerName` string, required — Customer's name.
    - `token` string, required — Token that the merchant can use in future transactions to represent the customer's payment details. The token: - Begins with the six-digit identification number **296753**. - Contains up to 12 digits. - Contains a single check digit that we calculate using the Luhn algorithm.
    - `status` 'notValidated' | 'cvvValidated' | 'validationFailed' | 'issueNumberValidated' | 'cardNumberValidated' | 'bankAccountValidated', required — Status of the customer's bank account. The processor performs a security check on the customer's bank account and returns the status of the account. **Note:** Depending on the merchant's account settings, this feature may be unavailable.
    - `link` Link — Object that contains HATEOAS links for the resource.
      - `rel` string, required — Indicates the relationship between the current resource and the target resource.
      - `method` string, required — HTTP method that you need to use with the target resource.
      - `href` string, required — URL of the target resource.
  - `name` string, required — Name of the subscription.
  - `description` string — Description of the subscription.
  - `currency` 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYR' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LTL' | 'LVL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRO' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STD' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'USS' | 'UYI' | 'UYU' | 'UZS' | 'VEF' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XOF' | 'XPF' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL', required — Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard.
  - `setupOrder` SubscriptionPaymentOrder — Object that contains information about the initial cost that a customer pays to set up the subscription.
    - `orderId` string — Unique identifier that the merchant assigns to the transaction.
    - `amount` integer — Total amount for the transaction. The value is in the currency's lowest denomination, for example, cents.<br/> <br/>**Important:** Do not add the surcharge to the amount parameter in the request. If the transaction is eligible for surcharging, our gateway adds the surcharge to the amount in the request, and then returns the updated amount in the response.
    - `description` string — Description of the transaction.
    - `breakdown` SubscriptionOrderBreakdown — Object that contains information about the surcharge and taxes that apply to the transaction.
      - `subtotal` integer, required — Total amount for the transaction before tax. The value is in the currency's lowest denomination, for example, cents.
      - `convenienceFee` ConvenienceFee — Object that contains information about the convenience fee for the transaction.
        - `amount` integer, required — If the merchant added a convenience fee, this value indicates the amount of the convenience fee in the currency’s lowest denomination, for example, cents.
      - `surcharge` Surcharge — Object that contains information about the surcharge.
        - `bypass` boolean — Indicates if the merchant wants to remove the surcharge fee from the transaction. - `true` - Gateway removes the surcharge fee from the transaction. - `false` - Gateway adds the fee to the transaction.
        - `amount` integer — If the merchant added a surcharge fee, this value indicates the amount of the surcharge fee in the currency’s lowest denomination, for example, cents.
        - `percentage` number, double — If the merchant added a surcharge fee, this value indicates the surcharge percentage.
      - `taxes` RetrievedTax[] — Array of tax objects.
        - `name` string, required — Name of the tax.
        - `rate` number, double, required — Tax percentage for the transaction.
        - `amount` integer — Amount of tax that was applied to the transaction. The value is in the currency's lowest denomination, for example, cents.
  - `recurringOrder` SubscriptionRecurringOrder — Object that contains information about the cost of each payment.
    - `amount` integer — Total amount for the transaction. The value is in the currency's lowest denomination, for example, cents.<br/> <br/>**Important:** Do not add the surcharge to the amount parameter in the request. If the transaction is eligible for surcharging, our gateway adds the surcharge to the amount in the request, and then returns the updated amount in the response.
    - `description` string — Description of the transaction.
    - `breakdown` SubscriptionOrderBreakdown — Object that contains information about the surcharge and taxes that apply to the transaction.
      - `subtotal` integer, required — Total amount for the transaction before tax. The value is in the currency's lowest denomination, for example, cents.
      - `convenienceFee` ConvenienceFee — Object that contains information about the convenience fee for the transaction.
        - `amount` integer, required — If the merchant added a convenience fee, this value indicates the amount of the convenience fee in the currency’s lowest denomination, for example, cents.
      - `surcharge` Surcharge — Object that contains information about the surcharge.
        - `bypass` boolean — Indicates if the merchant wants to remove the surcharge fee from the transaction. - `true` - Gateway removes the surcharge fee from the transaction. - `false` - Gateway adds the fee to the transaction.
        - `amount` integer — If the merchant added a surcharge fee, this value indicates the amount of the surcharge fee in the currency’s lowest denomination, for example, cents.
        - `percentage` number, double — If the merchant added a surcharge fee, this value indicates the surcharge percentage.
      - `taxes` RetrievedTax[] — Array of tax objects.
        - `name` string, required — Name of the tax.
        - `rate` number, double, required — Tax percentage for the transaction.
        - `amount` integer — Amount of tax that was applied to the transaction. The value is in the currency's lowest denomination, for example, cents.
  - `currentState` SubscriptionState, required — A snapshot of the subscription's current state.
    - `status` 'active' | 'completed' | 'suspended' | 'cancelled', required — Status of the Subscription. - 'active' - Subscription is active. - 'completed' - Subscription has reached the end date or the total number of billing cycles. - 'cancelled' - Merchant deactivated the subscription. - 'suspended' - Subscription is suspended. For example, if the customer misses payments.
    - `nextDueDate` string, date — Date that the merchant collects the next payment.
    - `paidInvoices` integer, required — Number of payments that the merchant has collected.
    - `outstandingInvoices` integer — Number of payments until the end of the subscription. Our gateway returns a value for **outstandingInvoices** only if the subscription has an end date or a fixed number of billing cycles.
  - `startDate` string, date, required — Format: **YYYY-MM-DD** Subscription's start date.
  - `endDate` string, date — Format: **YYYY-MM-DD** Subscription's end date. **Note:** If you provide values for both **length** and **endDate**, our gateway uses the value for **endDate** to determine when the subscription should end.
  - `length` integer — Total number of billing cycles. To indicate that the subscription should run indefinitely, send a value of `0`. This value replaces the **length** inherited from the payment plan. **Note:** If you provide values for both **length** and **endDate**, our gateway uses the value for **endDate** to determine when the subscription should end.
  - `type` 'manual' | 'automatic', required — How the merchant takes the payment from the customer’s account. - `manual` – The merchant manually collects payments from the customer. - `automatic` – The terminal automatically collects payments from the customer.
  - `frequency` 'weekly' | 'fortnightly' | 'monthly' | 'quarterly' | 'yearly', required — Indicates how often the merchant or the terminal collects a payment from the customer.
  - `pauseCollectionFor` integer — Number of billing cycles that the merchant wants to pause payments for. For example, if the merchant wants to offer a free trial period.
  - `customFields` CustomField[] — Array of customField objects.
    - `name` string, required — Name of the custom field.
    - `value` string, required — Value for the custom field.

## Other responses

- `400` — Validation error
- `401` — Identity could not be verified
- `403` — Do not have permissions to perform this action
- `404` — Resource not found
- `406` — Not acceptable
- `409` — Conflict
- `415` — Unsupported media type
- `500` — An error has occured

---

[API](https://skmtc.dev/payroc/apis/schema.md) · [All operations](https://skmtc.dev/payroc/apis/schema/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/payroc/schema/revisions/1d9d3e305945/schema)