Sign in

v1

latestOpenAPI 3.1.02026-07-24170121.2 MB

Create a Subscription

This API creates a subscription.

post/v1/subscriptions

Headers

Acceptstring required

Indicates which content types, expressed as MIME types, the client is able to understand.

Content-Typestring required

Indicates the media type of the resource sent in the HTTP message body. <br /><br /><b>Possible Values:</b><br /> application/json<br />application/x-www-form-urlencoded

Request body

customer_idstring 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_idstring 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_daysinteger

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_daysinteger

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_cyclesinteger

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_idstring

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_typeinteger

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_daysinteger

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>

descriptionstring

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

Example response

{
  "data": {
    "object": "Subscription",
    "id": "Vg0rxj00XXljPAoX",
    "customer_id": "jDPAnVxA4xPDVpKM",
    "billing_type": 1,
    "current_period_end": 1726490792,
    "current_period_start": 1726145192,
    "plan_ref": "n2pv6j6p2pvj3Ygq",
    "start_at": 1726490792,
    "status": "trial",
    "trial_end": 1726490792,
    "trial_days": 4,
    "trial_start": 1726145192,
    "created_at": 1726145192,
    "updated_at": 1726145192,
    "payment_type": "card",
    "pause_units_allowed": [
      "days"
    ],
    "plan": {
      "data": {
        "object": "Plan",
        "plan_id": "plan_d2b50d00",
        "amount": 99,
        "interval": "day",
        "interval_count": 1,
        "name": "test",
        "statement_descriptor": "dfghdfhg",
        "currency": "usd",
        "created_at": 1724503321,
        "updated_at": 1724505447
      }
    }
  },
  "meta": {
    "include": [
      "plan"
    ]
  }
}