Create Subscription

Creates a new subscription for an existing customer. When payment is required and no payment method exists, returns a checkout URL.

POST /api/v1/subscriptions

JavaScript

JavaScript

import Stigg from '@stigg/typescript';

const client = new Stigg({
  apiKey: process.env['STIGG_API_KEY'], // This is the default and can be omitted
});

const response = await client.v1.subscriptions.provision({
  customerId: 'customerId',
  planId: 'planId',
});

console.log(response.data);

201

{
  "data": {
    "id": "<string>",
    "subscription": {
      "id": "<string>",
      "customerId": "<string>",
      "billingId": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "startDate": "2023-11-07T05:31:56Z",
      "planId": "<string>",
      "payingCustomerId": "<string>",
      "resourceId": "<string>",
      "endDate": "2023-11-07T05:31:56Z",
      "effectiveEndDate": "2023-11-07T05:31:56Z",
      "cancellationDate": "2023-11-07T05:31:56Z",
      "trialEndDate": "2023-11-07T05:31:56Z",
      "metadata": {},
      "currentBillingPeriodStart": "2023-11-07T05:31:56Z",
      "currentBillingPeriodEnd": "2023-11-07T05:31:56Z",
      "billingCycleAnchor": "2023-11-07T05:31:56Z",
      "prices": [],
      "addons": [],
      "coupons": [],
      "futureUpdates": [],
      "budget": {
        "limit": 123,
        "hasSoftLimit": true
      },
      "minimumSpend": {
        "amount": 123
      },
      "subscriptionEntitlements": [],
      "latestInvoice": {
        "billingId": "<string>",
        "createdAt": "2023-11-07T05:31:56Z",
        "requiresAction": true,
        "total": 123,
        "amountDue": 123,
        "currency": "<string>",
        "pdfUrl": "<string>"
      },
      "trial": {}
    },
    "entitlements": [
      {
        "isGranted": true,
        "type": "FEATURE",
        "feature": {
          "id": "<string>",
          "displayName": "<string>"
        },
        "usageLimit": 1,
        "hasUnlimitedUsage": true,
        "currentUsage": 1,
        "usagePeriodAnchor": "2023-11-07T05:31:56Z",
        "usagePeriodStart": "2023-11-07T05:31:56Z",
        "usagePeriodEnd": "2023-11-07T05:31:56Z",
        "entitlementUpdatedAt": "2023-11-07T05:31:56Z",
        "validUntil": "2023-11-07T05:31:56Z"
      }
    ],
    "checkoutBillingId": "<string>",
    "checkoutUrl": "<string>",
    "isScheduled": true
  }
}

Authorizations

X-API-KEY · string · header · required

Server API Key

Headers

X-ACCOUNT-ID · string

Account ID — optional when authenticating with a user JWT (Bearer token); falls back to the user's first membership. Ignored for API-key auth.

X-ENVIRONMENT-ID · string

Environment ID — required when authenticating with a user JWT (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is intrinsic to the key).

Body

application/json

Provision a subscription. Returns subscription or checkout URL.

customerId · string · required

Customer ID to provision the subscription for

Required string length: 1 - 255

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$

planId · string · required

Plan ID to provision

Required string length: 1 - 255

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$

id · string

Unique identifier for the subscription

Required string length: 1 - 255

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$

payingCustomerId · string | null

Optional paying customer ID for split billing scenarios

Required string length: 1 - 255

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$

resourceId · string | null

Optional resource ID for multi-instance subscriptions

Required string length: 1 - 255

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$

billingPeriod · enum<string>

Billing period (MONTHLY or ANNUALLY)

Available options: MONTHLY, ANNUALLY

addons · SubscriptionAddon · object[]

Show child attributes

charges · SubscriptionCharge · object[]

Show child attributes

startDate · string<date-time>

Subscription start date

cancellationDate · string<date-time>

Subscription cancellation date

billingInformation · object

Show child attributes

billingId · string | null

External billing system identifier

Maximum string length: 255

billingCountryCode · string | null

The ISO 3166-1 alpha-2 country code for billing

Maximum string length: 255

entitlements · (SubscriptionFeatureEntitlementRequest · object | SubscriptionCreditEntitlementRequest · object)[]

Feature entitlement configuration for a subscription

SubscriptionFeatureEntitlementRequest

SubscriptionCreditEntitlementRequest

Show child attributes

trialOverrideConfiguration · object

Trial period override settings

Show child attributes

scheduleStrategy · enum<string>

Strategy for scheduling subscription changes

Available options: END_OF_BILLING_PERIOD, END_OF_BILLING_MONTH, IMMEDIATE

checkoutOptions · object

Checkout page configuration for payment collection

Show child attributes

metadata · object

Additional metadata for the subscription

Show child attributes

salesforceId · string | null

Salesforce ID

Maximum string length: 255

budget · object

Show child attributes

minimumSpend · object

Minimum spend amount

Show child attributes

priceOverrides · object[]

Show child attributes

paymentCollectionMethod · enum<string> · default: CHARGE

How payments should be collected for this subscription

Available options: CHARGE, INVOICE, NONE

appliedCoupon · SubscriptionCoupon · object

Coupon configuration

Show child attributes

awaitPaymentConfirmation · boolean · default: true

Whether to wait for payment confirmation before returning the subscription

unitQuantity · integer

Unit quantity for per-unit pricing. Minimum is 0 (zero is allowed).

Required range: x >= 0

billingCycleAnchor · enum<string>

Billing cycle anchor behavior for the subscription

Available options: UNCHANGED, NOW

Response

201

application/json

The newly created subscription object.

Response object

data · ProvisionSubscriptionResult · object · required

Provisioning result with status and subscription or checkout URL.

Show child attributes