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);

import os
from stigg import Stigg

client = Stigg(
    api_key=os.environ.get("STIGG_API_KEY"),  # This is the default and can be omitted
)
response = client.v1.subscriptions.provision(
    customer_id="customerId",
    plan_id="planId",
)
print(response.data)

package main

import (
	"context"
	"fmt"

	"github.com/stiggio/stigg-go"
	"github.com/stiggio/stigg-go/option"
)

func main() {
	client := stigg.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.V1.Subscriptions.Provision(context.TODO(), stigg.V1SubscriptionProvisionParams{
		CustomerID: "customerId",
		PlanID:     "planId",
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Data)
}

package io.stigg.example;

import io.stigg.client.StiggClient;
import io.stigg.client.okhttp.StiggOkHttpClient;
import io.stigg.models.v1.subscriptions.SubscriptionProvisionParams;
import io.stigg.models.v1.subscriptions.SubscriptionProvisionResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        StiggClient client = StiggOkHttpClient.fromEnv();

        SubscriptionProvisionParams params = SubscriptionProvisionParams.builder()
            .customerId("customerId")
            .planId("planId")
            .build();
        SubscriptionProvisionResponse response = client.v1().subscriptions().provision(params);
    }
}

require "stigg"

stigg = Stigg::Client.new(api_key: "My API Key")

response = stigg.v1.subscriptions.provision(customer_id: "customerId", plan_id: "planId")

puts(response)

using System;
using Stigg.Client;
using Stigg.Client.Models.V1.Subscriptions;

StiggClient client = new();

SubscriptionProvisionParams parameters = new()
{
    CustomerID = "customerId",
    PlanID = "planId",
};

var response = await client.V1.Subscriptions.Provision(parameters);

Console.WriteLine(response);

stigg v1:subscriptions provision \
  --api-key 'My API Key' \
  --customer-id customerId \
  --plan-id planId

curl --request POST \
  --url https://api.stigg.io/api/v1/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "customerId": "<string>",
  "planId": "<string>",
  "id": "<string>",
  "payingCustomerId": "<string>",
  "resourceId": "<string>",
  "addons": [
    {
      "id": "<string>",
      "quantity": 1
    }
  ],
  "charges": [
    {
      "id": "<string>",
      "quantity": 1
    }
  ],
  "startDate": "2023-11-07T05:31:56Z",
  "cancellationDate": "2023-11-07T05:31:56Z",
  "billingInformation": {
    "taxRateIds": [
      "<string>"
    ],
    "taxPercentage": 50,
    "billingAddress": {
      "city": "<string>",
      "country": "<string>",
      "line1": "<string>",
      "line2": "<string>",
      "postalCode": "<string>",
      "state": "<string>"
    },
    "metadata": {},
    "chargeOnBehalfOfAccount": "<string>",
    "isBackdated": false,
    "isInvoicePaid": false,
    "invoiceDaysUntilDue": 123,
    "integrationId": "<string>",
    "taxIds": [
      {
        "type": "<string>",
        "value": "<string>"
      }
    ]
  },
  "billingId": "<string>",
  "billingCountryCode": "<string>",
  "entitlements": [
    {
      "type": "FEATURE",
      "id": "<string>",
      "usageLimit": 1,
      "hasUnlimitedUsage": true,
      "hasSoftLimit": true,
      "yearlyResetPeriodConfiguration": {
        "accordingTo": "SubscriptionStart"
      },
      "monthlyResetPeriodConfiguration": {},
      "weeklyResetPeriodConfiguration": {}
    }
  ],
  "metadata": {},
  "salesforceId": "<string>",
  "budget": {
    "limit": 123,
    "hasSoftLimit": true
  },
  "minimumSpend": {
    "amount": 123
  },
  "priceOverrides": [
    {
      "amount": 123,
      "featureId": "<string>",
      "addonId": "<string>",
      "baseCharge": true,
      "billingCountryCode": "<string>",
      "blockSize": 123,
      "tiers": [
        {
          "upTo": 123
        }
      ]
    }
  ],
  "paymentCollectionMethod": "CHARGE",
  "appliedCoupon": {
    "couponId": "<string>",
    "billingCouponId": "<string>",
    "promotionCode": "<string>",
    "discount": {
      "name": "<string>",
      "description": "<string>",
      "durationInMonths": 2,
      "percentOff": 50.5,
      "amountsOff": [
        {
          "amount": 123
        }
      ]
    },
    "configuration": {
      "startDate": "2023-11-07T05:31:56Z"
    }
  },
  "awaitPaymentConfirmation": true,
  "unitQuantity": 1
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.stigg.io/api/v1/subscriptions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customerId' => '<string>',
    'planId' => '<string>',
    'id' => '<string>',
    'payingCustomerId' => '<string>',
    'resourceId' => '<string>',
    'addons' => [
        [
                'id' => '<string>',
                'quantity' => 1
        ]
    ],
    'charges' => [
        [
                'id' => '<string>',
                'quantity' => 1
        ]
    ],
    'startDate' => '2023-11-07T05:31:56Z',
    'cancellationDate' => '2023-11-07T05:31:56Z',
    'billingInformation' => [
        'taxRateIds' => [
                '<string>'
        ],
        'taxPercentage' => 50,
        'billingAddress' => [
                'city' => '<string>',
                'country' => '<string>',
                'line1' => '<string>',
                'line2' => '<string>',
                'postalCode' => '<string>',
                'state' => '<string>'
        ],
        'metadata' => [
                
        ],
        'chargeOnBehalfOfAccount' => '<string>',
        'isBackdated' => false,
        'isInvoicePaid' => false,
        'invoiceDaysUntilDue' => 123,
        'integrationId' => '<string>',
        'taxIds' => [
                [
                                'type' => '<string>',
                                'value' => '<string>'
                ]
        ]
    ],
    'billingId' => '<string>',
    'billingCountryCode' => '<string>',
    'entitlements' => [
        [
                'type' => 'FEATURE',
                'id' => '<string>',
                'usageLimit' => 1,
                'hasUnlimitedUsage' => true,
                'hasSoftLimit' => true,
                'yearlyResetPeriodConfiguration' => [
                                'accordingTo' => 'SubscriptionStart'
                ],
                'monthlyResetPeriodConfiguration' => [
                                
                ],
                'weeklyResetPeriodConfiguration' => [
                                
                ]
        ]
    ],
    'metadata' => [
        
    ],
    'salesforceId' => '<string>',
    'budget' => [
        'limit' => 123,
        'hasSoftLimit' => true
    ],
    'minimumSpend' => [
        'amount' => 123
    ],
    'priceOverrides' => [
        [
                'amount' => 123,
                'featureId' => '<string>',
                'addonId' => '<string>',
                'baseCharge' => true,
                'billingCountryCode' => '<string>',
                'blockSize' => 123,
                'tiers' => [
                                [
                                                                'upTo' => 123
                                ]
                ]
        ]
    ],
    'paymentCollectionMethod' => 'CHARGE',
    'appliedCoupon' => [
        'couponId' => '<string>',
        'billingCouponId' => '<string>',
        'promotionCode' => '<string>',
        'discount' => [
                'name' => '<string>',
                'description' => '<string>',
                'durationInMonths' => 2,
                'percentOff' => 50.5,
                'amountsOff' => [
                                [
                                                                'amount' => 123
                                ]
                ]
        ],
        'configuration' => [
                'startDate' => '2023-11-07T05:31:56Z'
        ]
    ],
    'awaitPaymentConfirmation' => true,
    'unitQuantity' => 1
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

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>",
      "contractId": "<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
  }
}

{
  "message": "<string>"
}

{
  "message": "<string>",
  "code": "Unauthenticated"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>",
  "code": "RateLimitExceeded"
}

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 | null

Show child attributes

minimumSpend · object | null

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