Provision 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>",
    "status": "SUCCESS",
    "subscription": {
      "id": "<string>",
      "customerId": "<string>",
      "billingId": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "startDate": "2023-11-07T05:31:56Z",
      "status": "PAYMENT_PENDING",
      "pricingType": "FREE",
      "paymentCollection": "NOT_REQUIRED",
      "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",
      "cancelReason": "UPGRADE_OR_DOWNGRADE",
      "metadata": {},
      "currentBillingPeriodStart": "2023-11-07T05:31:56Z",
      "currentBillingPeriodEnd": "2023-11-07T05:31:56Z",
      "paymentCollectionMethod": "CHARGE",
      "billingCycleAnchor": "2023-11-07T05:31:56Z",
      "prices": [],
      "addons": [],
      "coupons": [],
      "futureUpdates": [],
      "budget": {
        "limit": 123,
        "hasSoftLimit": true
      },
      "minimumSpend": {
        "amount": 123,
        "currency": "usd"
      },
      "subscriptionEntitlements": [],
      "latestInvoice": {
        "billingId": "<string>",
        "status": "OPEN",
        "createdAt": "2023-11-07T05:31:56Z",
        "requiresAction": true,
        "total": 123,
        "amountDue": 123,
        "currency": "<string>",
        "pdfUrl": "<string>",
        "billingReason": "BILLING_CYCLE"
      },
      "trial": {
        "trialEndBehavior": "CONVERT_TO_PAID"
      }
    },
    "entitlements": [
      {
        "isGranted": true,
        "type": "FEATURE",
        "accessDeniedReason": "FeatureNotFound",
        "usageLimit": 1,
        "hasUnlimitedUsage": true,
        "resetPeriod": "YEAR",
        "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

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 · Charge · object[]

Show child attributes

startDate · string<date-time>

Subscription start 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

Required range: x >= 1

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