---
title: "Create a Subscription"
method: POST
path: "/v1/subscriptions"
---

# Create a Subscription

`POST /v1/subscriptions`

This API creates a subscription.

## Headers

- `Accept` string, required
- `Content-Type` string, required

## Request body

- object
  - `customer_id` string, required — An ID against which a new subscription will be created.<br><style>td { padding: 2px 4px; border: 1px solid #ddd; font-size: 0.65em; line-height: 1.2; }</style><table style='width: 100%; border-collapse: collapse;'><tr><td style='text-align: center;'><b>Format</b></td><td style='text-align: center;'><b>Notes</b></td></tr><tr><td>Alphanumeric</td><td>Provide `customer_id` that was created using the Create a Customer API.</td></tr></table>
  - `plan_id` string, required — An plan ID against which a new subscription is created.<br><style>td { padding: 2px 4px; border: 1px solid #ddd; font-size: 0.65em; line-height: 1.2; }</style><table style='width: 100%; border-collapse: collapse;'><tr><td style='text-align: center;'><b>Format</b></td><td style='text-align: center;'><b>Notes</b></td></tr><tr><td>Alphanumeric and Special Characters</td><td>Provide `plan_id` that was created using the Create a Plan API.</td></tr></table>
  - `start_after_days` integer — Days after which the subscription will start.<br><style>td { padding: 2px 4px; border: 1px solid #ddd; font-size: 0.65em; line-height: 1.2; }</style><table style='width: 100%; border-collapse: collapse;'><tr><td style='text-align: center;'><b>Format</b></td><td style='text-align: center;'><b>Min Length</b></td><td style='text-align: center;'><b>Max Length</b></td></tr><tr><td>Numeric</td><td>1</td><td>365</td></tr></table>
  - `trial_days` integer — Number of days until the subscription is under the trial period.<br><style>td { padding: 2px 4px; border: 1px solid #ddd; font-size: 0.65em; line-height: 1.2; }</style><table style='width: 100%; border-collapse: collapse;'><tr><td style='text-align: center;'><b>Format</b></td><td style='text-align: center;'><b>Min Length</b></td><td style='text-align: center;'><b>Max Length</b></td><td style='text-align: center;'><b>Examples</b></td></tr><tr><td>Numeric</td><td>0</td><td>365</td><td>Created at: 2021-05-05<br>Trial Days: 3<br>What it means? Your billing for the subscription will start from 2021-05-08 till the end of the subscription period.</td></tr></table>
  - `end_after_cycles` integer — Number of cycles after which a subscription will end.<br><style>td { padding: 2px 4px; border: 1px solid #ddd; font-size: 0.65em; line-height: 1.2; }</style><table style='width: 100%; border-collapse: collapse;'><tr><td style='text-align: center;'><b>Format</b></td><td style='text-align: center;'><b>Min Length</b></td><td style='text-align: center;'><b>Max Length</b></td></tr><tr><td>Numeric</td><td>1</td><td>999</td></tr></table>
  - `discount_id` string — An ID that refers to a coupon when applying to a subscription. <br><style>td { padding: 2px 4px; border: 1px solid #ddd; font-size: 0.65em; line-height: 1.2; }</style><table style='width: 100%; border-collapse: collapse;'><tr><td style='text-align: center;'><b>Format</b></td><td style='text-align: center;'><b>Notes</b></td></tr><tr><td>Alphanumeric and Special Characters</td><td>Provide `discount_id` that was created using the Create a Coupon API. </td></tr></table>
  - `billing_type` integer — The type of billing applied to a subscription.<br><style>td { padding: 2px 4px; border: 1px solid #ddd; font-size: 0.65em; line-height: 1.2; }</style><table style='width: 100%; border-collapse: collapse;'><tr><td style='text-align: center;'><b>Format</b></td><td style='text-align: center;'><b>Default</b></td><td style='text-align: center;'><b>Min Length</b></td><td style='text-align: center;'><b>Max Length</b></td><td style='text-align: center;'><b>Notes</b></td></tr><tr><td>Boolean</td><td>1</td><td>0</td><td>1</td><td>`1` represents billing type is 'Automatic' where you will be charged with the default card on file. `0` represents customer billing type is 'Manual' where you will receive a payment link over an email.</td></tr></table>
  - `payment_due_days` integer — Number of days the payment is due after the invoice is sent.<br><style>td { padding: 2px 4px; border: 1px solid #ddd; font-size: 0.65em; line-height: 1.2; }</style><table style='width: 100%; border-collapse: collapse;'><tr><td style='text-align: center;'><b>Format</b></td><td style='text-align: center;'><b>Min Length</b></td><td style='text-align: center;'><b>Max Length</b></td><td style='text-align: center;'><b>Examples</b></td><td style='text-align: center;'><b>Notes</b></td></tr><tr><td>Numeric</td><td>1 digit</td><td>2 digits</td><td>`3`, `23`</td><td>This field is required if `billing_type` is 0.</td></tr></table>
  - `description` string — An arbitrary string that describes a subscription.<br><style>td { padding: 2px 4px; border: 1px solid #ddd; font-size: 0.65em; line-height: 1.2; }</style><table style='width: 100%; border-collapse: collapse;'><tr><td style='text-align: center;'><b>Format</b></td><td style='text-align: center;'><b>Min Length</b></td><td style='text-align: center;'><b>Max Length</b></td><td style='text-align: center;'><b>Examples</b></td></tr><tr><td>Alphanumeric and Special Characters</td><td>5 characters</td><td>200 characters</td><td>`A1 Company 888-888-8888`</td></tr></table>

## Response `201`

201

- object
  - `data` object
    - `object` string
    - `id` string
    - `customer_id` string
    - `application_fee_percent` number, nullable
    - `billing_type` integer
    - `payment_due_days` integer, nullable
    - `cancel_at_period_end` integer
    - `canceled_at` integer, nullable
    - `current_period_end` integer, nullable
    - `current_period_start` integer, nullable
    - `days_until_due` integer, nullable
    - `plan_ref` string
    - `start_at` integer, nullable
    - `end_at` integer, nullable
    - `status` 'active' | 'trial' | 'pending' | 'passed_due' | 'paused' | 'unpaid' | 'canceled'
    - `tax_percent` number
    - `trial_end` integer, nullable
    - `trial_days` integer
    - `trial_start` integer, nullable
    - `created_at` integer, nullable
    - `updated_at` integer, nullable
    - `description` string, nullable
    - `payment_type` string, nullable
    - `paused_at` integer, nullable
    - `pause_end_at` integer, nullable
    - `resumed_at` integer, nullable
    - `pause_units_allowed` string[]
    - `plan` object
      - `data` object
        - `object` string
        - `plan_id` string
        - `amount` integer
        - `interval` string
        - `interval_count` integer
        - `name` string
        - `plan_description` string, nullable
        - `statement_descriptor` string, nullable
        - `trial_period_days` union
          - string
          - integer
        - `currency` string
        - `created_at` integer, nullable
        - `updated_at` integer, nullable
  - `meta` object
    - `include` string[]
    - `custom` unknown[]
      - unknown

## Other responses

- `422` — 422

---

[API](https://skmtc.net/payarc/apis/payarc-sandbox.md) · [All operations](https://skmtc.net/payarc/apis/payarc-sandbox/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/payarc/payarc-sandbox/versions/face82bdd778/schema)