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

# Create Subscription

`POST /subscription/api/v1/subscriptions`

This endpoint creates a new subscription for a customer, enrolls the customer's card, and initiates the first payment where applicable.

### Important Notes

* **`cardDetails`** is mandatory when creating a subscription.
* If no trial period is configured, the first charge is attempted immediately after the card is enrolled.
* If a trial period is configured, the subscription is created with a status of **TRIALING**. The card is enrolled immediately, but the first charge is deferred until the trial period ends.
* When additional customer authentication is required, the subscription is created with a status of **REQUIRES_ACTION**, and the response includes the 3D Secure challenge details.
* Creating another active subscription using the same `customerEmail` returns a **409 Conflict** response.
* Before the first successful payment, the subscription remains in the **INCOMPLETE** state.
* The card service determines the charge mode (**DIRECT_CHARGE**, **TOKENIZATION**, or **AGREEMENT_BASED**) during card enrollment and returns it in the response. The subscription service stores this value for future recurring billing.

## Request body

- CreateSubscriptionRequest
  - `customerEmail` string, email, required — The customer's email address. Used to identify the customer's subscription. An email address can only have one active subscription per plan.
  - `planCode` string, required — The unique plan code generated when the subscription plan was created. If omitted, a plan is automatically created from the request.
  - `cardDetails` object, required — The card information used to enroll the customer for recurring billing.
    - `cardNumber` string, required — The customer's card number
    - `expiryMonth` string, required — The two-digit card expiry month.
    - `expiryYear` string, required — The two-digit card expiry year.
    - `securityCode` string, required — The CVV/CVC code.
    - `cardHolderName` string, required — The name printed on the payment card.
    - `present` boolean, required — To validate the card details.

## Response `200`

Subscription Created

- CreateSubscriptionResponse
  - `success` boolean — Indicates if the request was successful.
  - `message` string — Descriptive message regarding the subscription creation status.
  - `data` object — The payload containing the combined results of the subscription enrollment and initialization charge.
    - `subscription` object — Detailed entity information for the newly enrolled subscription.
      - `id` integer — Unique internal identifier for the subscription.
      - `customerId` string — The customer reference string identifier.
      - `customerEmail` string, email — Email address of the customer.
      - `firstName` string, nullable
      - `lastName` string, nullable
      - `customerAuthorizedAt` string, date-time, nullable
      - `status` string — The current lifecycle status of the subscription.
      - `currentPeriodStart` string, date-time — Timestamp indicating when the current billing window opened.
      - `currentPeriodEnd` string, date-time — Timestamp indicating when the current billing window closes.
      - `nextChargeDate` string, date-time — The next scheduled auto-billing execution timestamp.
      - `trialEndDate` string, date-time, nullable
      - `pauseResumesAt` string, date-time, nullable
      - `cancelAt` string, date-time, nullable
      - `pausedAt` string, date-time, nullable
      - `cancelledAt` string, date-time, nullable
      - `cancellationReason` string, nullable
      - `cardExpiryAlertSent` boolean
      - `connectionMode` string
      - `enrollmentReference` string — The global token signature identifying the authorized card reference.
      - `enrollmentTxnReference` string — Transaction baseline reference tracking the enrollment event.
      - `chargeMode` string
      - `metadata` object, nullable
      - `createdAt` string, date-time
      - `updatedAt` string, date-time
      - `customerBearsFee` boolean
      - `enrollConfirmed` boolean
    - `chargeResult` object — Realtime transaction processing outcome details for the initial subscription authorization charge.
      - `charged` boolean
      - `status` string
      - `amount` number
      - `fees` number
      - `currency` string
      - `transactionReference` string
      - `authCode` string
      - `chargeMode` string
      - `message` string

## Other responses

- `400` — Invalid request

---

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