v1

latestOpenAPI 3.0.02026-07-26167441.9 MB

Create Subscription

post/subscriptions

Headers

x-idempotency-keystring

A unique identifier for the request. Must be different each time (UUID). See authentication.

Request body

namestring required

The subscription plan name (MAX 255; MIN 3).

descriptionstring

The subscription plan description (MAX 255; MIN 3).

account_idstring required

The unique identifier of the account that will have the subscription plan available to use (UUID, 36 chars).

merchant_referencestring

Identification of the subscription plan (MAX 255; MIN 3).

soft_descriptorstring

Statement descriptor shown on the cardholder's bank statement. When set, it is persisted on the subscription and propagated to every rebill payment generated by the subscription engine. Length and formatting limits vary by provider (for example, Unlimit truncates to 22 characters and Airwallex to 30). Worldpay does not read this field; it builds the statement narrative from payment_description instead.

countrystring required

The subscription's country (MAX 2; MIN 2; ISO 3166-1).

plan_idstring

The unique identifier of a plan to subscribe this customer to. Mutually exclusive with amount — send exactly one of the two. Omit trial_period and billing_date when set: both are inherited from the plan and the request is rejected with 400 BAD_REQUEST if you send them. Also omit frequency — it's inherited from the plan too, but sending it anyway is not rejected: it's silently ignored and overridden by the plan's frequency.

initial_payment_validationboolean

Flag to identify if the subscription should wait for the first payment in order to continue. False by default.

subscription_agreement_idstring

Links this subscription to the initial payment created with the same agreement ID. Used for tracking, reconciliation, and chargeback handling. Must exactly match the subscription_agreement_id sent in payment_method.detail.card.stored_credentials.subscription_agreement_id on the originating payment (MAX 255).

Response

200

idstring

namestring

account_idstring

countrystring

descriptionstring

merchant_referencestring

soft_descriptorstring

statusstring

{"stackTrail":"paths:/subscriptions:post:responses:200:content:application/json:schema:properties:metadata","oasType":"schema","type":"unknown"}

plan_idstring

Only present when the subscription is linked to a plan.

plan_assigned_atstring

Only present on plan-linked subscriptions. The moment the plan was attached — at creation from a plan, migration onto a plan, or a plan change.

previous_subscription_idstring

Only present when this subscription was created by a plan change (switching an existing subscription to a different plan).

current_phasestring

Only present on plan-linked subscriptions.

subscription_agreement_idstring

created_atstring

updated_atstring

Example response

{
  "id": "0c7fed3e-ee0d-4d34-9547-778be4ec0798",
  "name": "Test Subscription",
  "account_id": "493e9374-510a-4201-9e09-de669d75f256",
  "country": "US",
  "description": "Subscription Test",
  "merchant_reference": "subscription-ref-merchant-AA01",
  "soft_descriptor": "ACME SUBSCRIPTION",
  "status": "ACTIVE",
  "amount": {
    "currency": "USD",
    "value": 15000
  },
  "frequency": {
    "type": "MONTH",
    "value": 1
  },
  "billing_cycles": {
    "total": 12,
    "current": 1,
    "next_at": "2024-09-30T12:04:23.265393Z"
  },
  "customer_payer": {
    "id": "a1d3b664-e32a-4508-9da1-9ede3e62a60c"
  },
  "payment_method": {
    "type": "CARD",
    "vaulted_token": "d4aa3586-def2-4705-b7cd-fe064bb764e6"
  },
  "availability": {
    "start_at": "2024-09-30T12:04:23.265393Z"
  },
  "trial_period": {
    "billing_cycles": 1
  },
  "subscription_agreement_id": "sa_6af2dfcd-44c0-4f16-a331-8bed3ed9c9fa",
  "created_at": "2024-09-30T12:04:23.265372Z",
  "updated_at": "2024-09-30T12:04:23.265372Z"
}