Subscriptions

SubscriptionsAPI allow you to charge customers on a recurring basis. A successful subscription flow follows this sequence:

1. The subscription is created with a status of pending
2. On the billing_cycle_anchor date, a Payment Intent is created and confirmed
3. The subscription status is then updated to active
4. The subscription remains in the active status indefinitely or until it reaches the specified cancel_at date, at which point its status changes to canceled

Set Up a Subscription

To set up a new subscription, you need an existing customer and their associated payment method.

curl -L '{{PRODUCTION_API_URL}}/v1/customers' \
    -H '{{ACCOUNT_HEADER}}-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'Content-Type: application/json' \
    -H '{{ACCOUNT_HEADER}}-api-key: {{SECRET_KEY}}' \
  -d '{
  "email": "test@email.test",
  "first_name": "Jane",
    "middle_name": "Andrea",
  "last_name": "Doe",
  "metadata": {
    "order_id": "100123",
    "internal_customer_id": "7cb1159d-875e-47ae-a309-319fa7ff395b"
  },
  "phone": "1234567890"
}'

curl -L '{{PRODUCTION_API_URL}}/v1/payment-methods' \
    -H '{{ACCOUNT_HEADER}}-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'Content-Type: application/json' \
    -H '{{ACCOUNT_HEADER}}-api-key: {{SECRET_KEY}}' \
  -d '{
    "type": "card",
    "card": {
        "number": "4111111111111111",
        "exp_month": 12,
        "exp_year": 2031,
        "cvc": "123"
    },
    "billing_details": {
        "address": {
            "zip": "33139"
        }
    }
}'

curl -L -X PUT '{{PRODUCTION_API_URL}}/v1/payment-methods/{{PAYMENT_METHOD_ID}}/attach' \
    -H '{{ACCOUNT_HEADER}}-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'Content-Type: application/json' \
    -H '{{ACCOUNT_HEADER}}-api-key: {{SECRET_KEY}}' \
  -d '{
    "customer_id": "{{CUSTOMER_ID}}"
}'

curl -L '{{PRODUCTION_API_URL}}/v1/subscriptions' \
    -H '{{ACCOUNT_HEADER}}-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'Content-Type: application/json' \
    -H '{{ACCOUNT_HEADER}}-api-key: {{SECRET_KEY}}' \
  -d '{
  "billing_cycle_anchor": "2024-07-04",
  "currency": "usd",
  "customer_id":  “{{CUSTOMER_ID}}”,
  "interval_count": 1,
  "interval_unit": "week",
  "metadata": {
    "order_id": "100123",
    "internal_customer_id": "7cb1159d-875e-47ae-a309-319fa7ff395b"
  },
  "payment_method_id": "{{PAYMENT_METHOD_ID}}",
  "platform_fee_amount": 500,
  "price": 10000
}'

Manage a Subscription

Although you can't change the customer or billing cycle associated with a subscription, you can update the payment method as needed. Subscriptions can also be paused, resumed, and canceled.

Define billing cycle

Billing cycles are calculated using a combination of billing_cycle_anchor, interval_unit, and interval_count. The billing_cycle_anchor sets the first payment date and determines the schedule for subsequent payments — whether they occur weekly, monthly, or yearly.

If the scheduled payment day does not exist in a given month, the payment will default to the last day of that month. For instance, a subscription that starts on January 31 would next be billed on February 28 (or 29 in a leap year), then on March 31 and so on. The interval_count specifies how many intervals, as defined by the interval_unit, will pass between billings.

Pause a subscription

Pausing a subscription temporarily stops all payment attempts, giving you flexibility in managing customer accounts.

• Pause immediately: Pause a subscription immediately using the Pause a SubscriptionAPI endpoint.
• Pause on a future date: Set the pause_at attribute to define a future date for when the subscription should be paused. This can be done when you Create a SubscriptionAPI or Update a SubscriptionAPI.

Resume a subscription

Resuming a subscription reactivates the billing cycle and continues the regular payment schedule.

• Resume immediately: Resume a subscription immediately using the Resume a SubscriptionAPI endpoint.
• Resume on a future date: Set the resume_at attribute to define a future date for when the subscription should resume. This can be done when you Create a SubscriptionAPI or Update a SubscriptionAPI.

Cancel a subscription

Canceling a subscription permanently stops all future payments.

• Cancel immediately: Cancel a subscription immediately using the Cancel a SubscriptionAPI endpoint.
• Cancel on a future date: Set the cancel_at attribute to define a future date for the subscription cancellation. This can be done when you Create a SubscriptionAPI or Update a SubscriptionAPI.

Subscription States

Subscription Events

Subscriptions trigger three specific types of events:

• subscription.created
• subscription.updated
• subscription.canceled

Events related to Payment Intents are also generated and will include the subscription_id in the event payload.

When you create a customer with a valid payment method and associate them with a subscription, the following events will be triggered, although their exact order may vary:

• customer.created: Indicates that a customer record has been successfully created.
• payment_method.attached: Indicates that a payment method has been successfully attached to the customer.
• subscription.created: Indicates that the subscription has been created.
• payment_intent.created, payment_intent.succeeded, and charge.succeeded: These events indicate that the customer's payment method was successfully charged.
• subscription.updated: This event is sent when the subscription status changes to active, and the payload includes the next_payment_at date, which is when the next automatic payment attempt will occur.

Using Subscriptions to Schedule One-Time Payments

While SubscriptionsAPI are primarily designed for recurring payments, they can also be adapted to schedule a one-time future payment. To implement this, first Create a CustomerAPI, Attach a Payment Method to a CustomerAPI, then you can Create a SubscriptionAPI and set the cancel_at attribute to the day after the billing_cycle_anchor date.

Create a Subscription sample request

curl -L '{{PRODUCTION_API_URL}}/v1/subscriptions' \
    -H '{{ACCOUNT_HEADER}}-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'Content-Type: application/json' \
    -H '{{ACCOUNT_HEADER}}-api-key: {{SECRET_KEY}}' \
  -d '{
  "billing_cycle_anchor": "2024-07-04",
  "cancel_at": "2025-07-05",
  "currency": "usd",
  "customer_id":  “{{CUSTOMER_ID}}”,
  "interval_count": 1,
  "interval_unit": "week",
  "metadata": {
    "order_id": "100123",
    "internal_customer_id": "7cb1159d-875e-47ae-a309-319fa7ff395b"
  },
  "payment_method_id": "{{PAYMENT_METHOD_ID}}",
  "platform_fee_amount": 500,
  "price": 10000
}'