---
title: "Create Subscription"
method: POST
path: "/v1/subscriptions"
tags: ["Subscriptions"]
---

# Create Subscription

`POST /v1/subscriptions`

The following endpoint registers a recurring billing agreement for a customer and returns the subscription in `pending` status. No payment method is collected at this step. The subscription is activated separately by its first payment (hosted checkout, or the Charge Subscription endpoint).

## Headers

- `Content-Type` string, required
- `X-Request-ID` string

## Request body

- object
  - `customer_id` string, required — Durianpay customer ID.
  - `amount` object, required
    - `currency` string, required — Currency code. Only supports "IDR"
    - `value` string, required — Recurring charge amount
  - `interval` 'daily' | 'weekly' | 'monthly' | 'annually', required — Billing frequency unit.
  - `interval_count` integer — Multiplier for interval (3 + monthly = every 3 months). Defaults to 1.
  - `return_url` string, uri, required — URL the customer is redirected to after hosted checkout.
  - `subscription_ref_id` string — Optional. Your own reference for this subscription, returned unchanged for reconciliation.

## Response `201`

Subscription created in pending status.

- object
  - `status` string
  - `data` object
    - `id` string
    - `merchant_id` string
    - `customer_id` string
    - `amount` object — Recurring charge amount as a currency and decimal-string value, e.g. {"currency":"IDR","value":"10000.00"}.
      - `currency` string, required — Currency code. IDR only in V1.
      - `value` string, required — Decimal string amount.
    - `interval` 'daily' | 'weekly' | 'monthly' | 'annually' — Billing frequency unit.
    - `interval_count` integer
    - `status` 'pending' | 'active' | 'past_due' | 'paused' | 'cancelled'
    - `checkout_url` string — Durianpay-hosted activation page for the first payment.
    - `return_url` string
    - `subscription_ref_id` string, nullable — Your own reference, echoed back. Null if not supplied.
    - `next_billing_date` string, date-time, nullable — Null until the subscription becomes active.
    - `payment_method_type` string, nullable — Null until the first payment succeeds.
    - `cancellation_reason` 'merchant_cancelled' | 'payment_failed' | 'expired' | 'completed', nullable
    - `metadata` object, nullable
    - `created_at` string, date-time
    - `updated_at` string, date-time

## Other responses

- `400` — Invalid or missing request fields.
- `403` — Subscription feature is not enabled for this merchant.
- `404` — The referenced customer does not exist for this merchant.

---

[API](https://skmtc.net/durianpay/apis/durianpay-api.md) · [All operations](https://skmtc.net/durianpay/apis/durianpay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/durianpay/durianpay-api/revisions/ffc0e7e8a227/schema)