post http://{{url}}/v1/subscriptions/
Update subscription settings or/and apply an additional flow.
Additional Flow
- Restart a subscription starting on a specific day. (The payment cycle will start on the specified date.)
- Reactivate an expired or deleted subscription starting on a specific day by updating its status to active. (The payment cycle will start on the specified date.)
- Reactivate a failed subscription by updating the status to active. After reactivation, the system will charge all the skipped payments.
- Transfer an active subscription to the held status. Records on charges will still be created, however, the payment itself is not sent to the gateway and thus not processed.
- Transfer a held subscription to the active status. All held charges remain held, i.e. it is not possible to re-process them.
- Transfer a subscription to the final status (deleted or expired) manually.
Status modification
The diagram below shows all possible ways of status modification and how it affects the payment cycle.
Request params
| field | required | type | description |
|---|---|---|---|
| id | + | string (24 hex characters) | The ID received at the creation stage |
Request body
| field | required [flow] | type | description |
|---|---|---|---|
| amount | - | float | An amount of the payment |
| currency | - | string (iso4217 alpha-3) | The currency code |
| description | - | string | A manually defined description for payments in payment systems |
| reference | - | string | A manually defined reference for payments in payment systems |
| payment_source_id | - | string(24 hex characters) | The payment source to pay for the subscription, generally a payment source retrieved from a customer is used |
| status | +2,+3,+4,+5,+6 | string | A new subscription status. |
| schedule | - | object | An object with subscription schedule information |
| schedule.interval | - | string | An assessment interval. Possible values: one-off, week, month, year, day |
| schedule.frequency | - | string (numeric) | An assessment frequency, 1 is used by default (i.e. “3” = “Every 3 weeks”) |
| schedule.start_date | +1, +2 | string (Date) | A start date can be provided in the ISO 8601 format (yyyy-mm-ddThh:mm:ss.sssZ) or in a short type of date (yyyy-mm-dd) or with time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm). The date in the past is automatically converted to the current moment |
| schedule.end_date | - | string (Date) | An end date can be provided in the ISO 8601 format (yyyy-mm-ddThh:mm:ss.sssZ) or in a short type of date (yyyy-mm-dd) or with time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm) |
| schedule.end_amount_after | - | float | A total amount of all successful transactions (equals or exceeds) |
| schedule.end_amount_before | - | float | A total amount of all successful transactions (not to exceed) |
| schedule.end_amount_total | - | float | A total amount to be paid with subscription (equals). NOTE: If the last payment of subscription schedule will be less than $ 1.00, some gateways may respond with an error and the subscription status will become ‘failed’. |
| schedule.end_transactions | - | integer | A total count of all successful transactions |
| retry | - | object | An optional object with specific fields for retry settings. The settings are applied after a payment on a subscription fails with a soft error |
| retry.limit | - | integer | A maximum amount of retried payments |
| retry.frequency | - | integer | A retry frequency, 1 is used by default (i.e. “3” = “Every 3 weeks”) |
| retry.interval | - | string | A retry interval. Possible values: week, month, year, day |
| retry.fail_status | - | string | A status of the subscription after all the retries have gone through (active, held, failed, deleted, etc.) |