Skip to main content
POST
/
api
/
external
/
v2
/
subscription-contract-details
/
create-subscription-contract
Create a new subscription contract
curl --request POST \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details/create-subscription-contract \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "billingIntervalCount": 1,
  "billingIntervalType": "MONTH",
  "customerId": "987654321",
  "deliveryAddress1": "123 Main St",
  "deliveryCity": "New York",
  "deliveryCountryCode": "US",
  "lines": [
    {
      "quantity": 2,
      "variantId": "42549172011164",
      "currentPrice": 25.99,
      "customAttributes": [
        {
          "key": "engraving",
          "value": "Happy Birthday"
        }
      ],
      "linePricingPolicy": "SELLING_PLAN_PRICING_POLICY",
      "pricingPolicy": [
        {
          "afterCycle": 3,
          "discountType": "PERCENTAGE",
          "freeProductHandle": "free-gift-product",
          "freeProductTitle": "Ceramic Mug",
          "freeVariantId": 42549172011164,
          "preventDuplicationFreeProduct": true,
          "repeatingCycle": true,
          "repeatingNumberOfCycle": 6,
          "value": 10
        }
      ],
      "productId": "7234567890123",
      "sellingPlanId": "gid://shopify/SellingPlan/123456",
      "unitPrice": 29.99
    }
  ],
  "nextBillingDate": "2024-02-01T00:00:00Z",
  "status": "ACTIVE"
}
'
import requests

url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details/create-subscription-contract"

payload = {
    "billingIntervalCount": 1,
    "billingIntervalType": "MONTH",
    "customerId": "987654321",
    "deliveryAddress1": "123 Main St",
    "deliveryCity": "New York",
    "deliveryCountryCode": "US",
    "lines": [
        {
            "quantity": 2,
            "variantId": "42549172011164",
            "currentPrice": 25.99,
            "customAttributes": [
                {
                    "key": "engraving",
                    "value": "Happy Birthday"
                }
            ],
            "linePricingPolicy": "SELLING_PLAN_PRICING_POLICY",
            "pricingPolicy": [
                {
                    "afterCycle": 3,
                    "discountType": "PERCENTAGE",
                    "freeProductHandle": "free-gift-product",
                    "freeProductTitle": "Ceramic Mug",
                    "freeVariantId": 42549172011164,
                    "preventDuplicationFreeProduct": True,
                    "repeatingCycle": True,
                    "repeatingNumberOfCycle": 6,
                    "value": 10
                }
            ],
            "productId": "7234567890123",
            "sellingPlanId": "gid://shopify/SellingPlan/123456",
            "unitPrice": 29.99
        }
    ],
    "nextBillingDate": "2024-02-01T00:00:00Z",
    "status": "ACTIVE"
}
headers = {
    "X-API-Key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    billingIntervalCount: 1,
    billingIntervalType: 'MONTH',
    customerId: '987654321',
    deliveryAddress1: '123 Main St',
    deliveryCity: 'New York',
    deliveryCountryCode: 'US',
    lines: [
      {
        quantity: 2,
        variantId: '42549172011164',
        currentPrice: 25.99,
        customAttributes: [{key: 'engraving', value: 'Happy Birthday'}],
        linePricingPolicy: 'SELLING_PLAN_PRICING_POLICY',
        pricingPolicy: [
          {
            afterCycle: 3,
            discountType: 'PERCENTAGE',
            freeProductHandle: 'free-gift-product',
            freeProductTitle: 'Ceramic Mug',
            freeVariantId: 42549172011164,
            preventDuplicationFreeProduct: true,
            repeatingCycle: true,
            repeatingNumberOfCycle: 6,
            value: 10
          }
        ],
        productId: '7234567890123',
        sellingPlanId: 'gid://shopify/SellingPlan/123456',
        unitPrice: 29.99
      }
    ],
    nextBillingDate: '2024-02-01T00:00:00Z',
    status: 'ACTIVE'
  })
};

fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details/create-subscription-contract', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
const url = 'https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details/create-subscription-contract';
const options = {
  method: 'POST',
  headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    billingIntervalCount: 1,
    billingIntervalType: 'MONTH',
    customerId: '987654321',
    deliveryAddress1: '123 Main St',
    deliveryCity: 'New York',
    deliveryCountryCode: 'US',
    lines: [
      {
        quantity: 2,
        variantId: '42549172011164',
        currentPrice: 25.99,
        customAttributes: [{key: 'engraving', value: 'Happy Birthday'}],
        linePricingPolicy: 'SELLING_PLAN_PRICING_POLICY',
        pricingPolicy: [
          {
            afterCycle: 3,
            discountType: 'PERCENTAGE',
            freeProductHandle: 'free-gift-product',
            freeProductTitle: 'Ceramic Mug',
            freeVariantId: 42549172011164,
            preventDuplicationFreeProduct: true,
            repeatingCycle: true,
            repeatingNumberOfCycle: 6,
            value: 10
          }
        ],
        productId: '7234567890123',
        sellingPlanId: 'gid://shopify/SellingPlan/123456',
        unitPrice: 29.99
      }
    ],
    nextBillingDate: '2024-02-01T00:00:00Z',
    status: 'ACTIVE'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details/create-subscription-contract",
  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([
    'billingIntervalCount' => 1,
    'billingIntervalType' => 'MONTH',
    'customerId' => '987654321',
    'deliveryAddress1' => '123 Main St',
    'deliveryCity' => 'New York',
    'deliveryCountryCode' => 'US',
    'lines' => [
        [
                'quantity' => 2,
                'variantId' => '42549172011164',
                'currentPrice' => 25.99,
                'customAttributes' => [
                                [
                                                                'key' => 'engraving',
                                                                'value' => 'Happy Birthday'
                                ]
                ],
                'linePricingPolicy' => 'SELLING_PLAN_PRICING_POLICY',
                'pricingPolicy' => [
                                [
                                                                'afterCycle' => 3,
                                                                'discountType' => 'PERCENTAGE',
                                                                'freeProductHandle' => 'free-gift-product',
                                                                'freeProductTitle' => 'Ceramic Mug',
                                                                'freeVariantId' => 42549172011164,
                                                                'preventDuplicationFreeProduct' => true,
                                                                'repeatingCycle' => true,
                                                                'repeatingNumberOfCycle' => 6,
                                                                'value' => 10
                                ]
                ],
                'productId' => '7234567890123',
                'sellingPlanId' => 'gid://shopify/SellingPlan/123456',
                'unitPrice' => 29.99
        ]
    ],
    'nextBillingDate' => '2024-02-01T00:00:00Z',
    'status' => 'ACTIVE'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <x-api-key>"
  ],
]);

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

curl_close($curl);

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

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details/create-subscription-contract"

	payload := strings.NewReader("{\n  \"billingIntervalCount\": 1,\n  \"billingIntervalType\": \"MONTH\",\n  \"customerId\": \"987654321\",\n  \"deliveryAddress1\": \"123 Main St\",\n  \"deliveryCity\": \"New York\",\n  \"deliveryCountryCode\": \"US\",\n  \"lines\": [\n    {\n      \"quantity\": 2,\n      \"variantId\": \"42549172011164\",\n      \"currentPrice\": 25.99,\n      \"customAttributes\": [\n        {\n          \"key\": \"engraving\",\n          \"value\": \"Happy Birthday\"\n        }\n      ],\n      \"linePricingPolicy\": \"SELLING_PLAN_PRICING_POLICY\",\n      \"pricingPolicy\": [\n        {\n          \"afterCycle\": 3,\n          \"discountType\": \"PERCENTAGE\",\n          \"freeProductHandle\": \"free-gift-product\",\n          \"freeProductTitle\": \"Ceramic Mug\",\n          \"freeVariantId\": 42549172011164,\n          \"preventDuplicationFreeProduct\": true,\n          \"repeatingCycle\": true,\n          \"repeatingNumberOfCycle\": 6,\n          \"value\": 10\n        }\n      ],\n      \"productId\": \"7234567890123\",\n      \"sellingPlanId\": \"gid://shopify/SellingPlan/123456\",\n      \"unitPrice\": 29.99\n    }\n  ],\n  \"nextBillingDate\": \"2024-02-01T00:00:00Z\",\n  \"status\": \"ACTIVE\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
require 'uri'
require 'net/http'

url = URI("https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details/create-subscription-contract")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"billingIntervalCount\": 1,\n  \"billingIntervalType\": \"MONTH\",\n  \"customerId\": \"987654321\",\n  \"deliveryAddress1\": \"123 Main St\",\n  \"deliveryCity\": \"New York\",\n  \"deliveryCountryCode\": \"US\",\n  \"lines\": [\n    {\n      \"quantity\": 2,\n      \"variantId\": \"42549172011164\",\n      \"currentPrice\": 25.99,\n      \"customAttributes\": [\n        {\n          \"key\": \"engraving\",\n          \"value\": \"Happy Birthday\"\n        }\n      ],\n      \"linePricingPolicy\": \"SELLING_PLAN_PRICING_POLICY\",\n      \"pricingPolicy\": [\n        {\n          \"afterCycle\": 3,\n          \"discountType\": \"PERCENTAGE\",\n          \"freeProductHandle\": \"free-gift-product\",\n          \"freeProductTitle\": \"Ceramic Mug\",\n          \"freeVariantId\": 42549172011164,\n          \"preventDuplicationFreeProduct\": true,\n          \"repeatingCycle\": true,\n          \"repeatingNumberOfCycle\": 6,\n          \"value\": 10\n        }\n      ],\n      \"productId\": \"7234567890123\",\n      \"sellingPlanId\": \"gid://shopify/SellingPlan/123456\",\n      \"unitPrice\": 29.99\n    }\n  ],\n  \"nextBillingDate\": \"2024-02-01T00:00:00Z\",\n  \"status\": \"ACTIVE\"\n}"

response = http.request(request)
puts response.read_body
{
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1,
    "maxCycles": 12,
    "minCycles": 3
  },
  "customer": {
    "email": "customer@example.com",
    "firstName": "John",
    "id": "gid://shopify/Customer/987654321",
    "lastName": "Doe"
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "deliveryPrice": {
    "amount": "5.99",
    "currencyCode": "USD"
  },
  "id": "gid://shopify/SubscriptionContract/123456789",
  "lines": {
    "edges": [
      {
        "node": {
          "currentPrice": {
            "amount": "25.99",
            "currencyCode": "USD"
          },
          "id": "gid://shopify/SubscriptionLine/111111",
          "pricingPolicy": {
            "basePrice": {
              "amount": "29.99",
              "currencyCode": "USD"
            }
          },
          "quantity": 2,
          "variantId": "gid://shopify/ProductVariant/42549172011164"
        }
      }
    ]
  },
  "nextBillingDate": "2024-02-01T00:00:00Z",
  "status": "ACTIVE"
}

Headers

​
X-API-Key
string
required

API Key

Query Parameters

​
api_key
string

API Key (Deprecated)

Body

application/json

Request object for creating a new subscription contract

​
billingIntervalCount
integer<int32>
required

Number of intervals between billings

Required range: x >= 1
Example:

1

​
billingIntervalType
enum<string>
required

Billing frequency interval type

Available options:
DAY,
WEEK,
MONTH,
YEAR,
$UNKNOWN,
DAY,
WEEK,
MONTH,
YEAR
Example:

"MONTH"

​
customerId
string
required

Shopify customer ID (numeric ID without gid prefix)

Example:

"987654321"

​
deliveryAddress1
string
required

Delivery address line 1

Example:

"123 Main St"

​
deliveryCity
string
required

Delivery address city

Example:

"New York"

​
deliveryCountryCode
string
required

Delivery address country code (ISO 3166-1 alpha-2)

Example:

"US"

​
lines
object[]
required

Product line items to include in the subscription

​
nextBillingDate
string<date-time>
required

Date when the next billing/order will occur

Example:

"2024-02-01T00:00:00Z"

​
status
enum<string>
required

Initial status of the subscription contract

Available options:
ACTIVE,
PAUSED,
CANCELLED,
EXPIRED,
FAILED,
$UNKNOWN,
ACTIVE,
PAUSED,
CANCELLED,
EXPIRED,
FAILED
Example:

"ACTIVE"

​
allowDeliveryAddressOverride
boolean
default:false

Allow customer to change delivery address in customer portal

Example:

false

​
allowDeliveryPriceOverride
boolean
default:false

Allow delivery price to be overridden

Example:

false

​
createWithoutPaymentMethod
boolean
default:false

If true, creates subscription without payment method. Status will be set to PAUSED unless skipPaymentCreateUnpaidOrder is also true.

Example:

false

​
currencyCode
string

Currency code for the subscription (ISO 4217). If not provided, uses store default currency

Example:

"USD"

​
customAttributes
object[]

Custom attributes to attach to the subscription contract

Example:
[
  {
    "key": "subscription_type",
    "value": "premium"
  },
  {
    "key": "gift_message",
    "value": "Happy Birthday!"
  }
]
​
deliveryAddress2
string

Delivery address line 2

Example:

"Apt 4B"

​
deliveryFirstName
string

Delivery address first name

Example:

"John"

​
deliveryIntervalCount
integer<int32>

Number of intervals between deliveries. If not specified, uses billing interval count

Required range: x >= 1
Example:

1

​
deliveryIntervalType
enum<string>

Delivery frequency interval type. If not specified, uses billing interval

Available options:
DAY,
WEEK,
MONTH,
YEAR,
$UNKNOWN,
DAY,
WEEK,
MONTH,
YEAR
Example:

"MONTH"

​
deliveryLastName
string

Delivery address last name

Example:

"Doe"

​
deliveryPhone
string

Delivery phone number

Example:

"+1234567890"

​
deliveryPriceAmount
number<double>

Fixed delivery price amount in store currency

Example:

5.99

​
deliveryProvinceCode
string

Delivery address province/state code (ISO 3166-2)

Example:

"NY"

​
deliveryZip
string

Delivery address postal/zip code

Example:

"10001"

​
maxCycles
integer<int32>

Maximum number of billing cycles. Null for unlimited

Required range: x >= 1
Example:

12

​
minCycles
integer<int32>

Minimum number of billing cycles required before cancellation is allowed

Required range: x >= 1
Example:

3

​
paymentMethodId
string

Customer payment method ID. If not provided, the default payment method will be used. Can be null if createWithoutPaymentMethod is true.

Example:

"gid://shopify/CustomerPaymentMethod/abc123"

​
skipPaymentCreateUnpaidOrder
boolean
default:false

If true, billing attempts on this contract will create unpaid orders instead of failing when no payment method is present. Requires createWithoutPaymentMethod=true. Contract will be created as ACTIVE (not PAUSED) so billing can proceed.

Example:

false

Response

Subscription contract successfully created

​
billingAttempts
object
​
billingPolicy
object
​
createdAt
object
​
customAttributes
object[]
​
customer
object
​
customerPaymentMethod
object
​
deliveryMethod
object
​
deliveryPolicy
object
​
deliveryPrice
object
​
discounts
object
​
get__typename
string
​
id
string
​
lastPaymentStatus
enum<string>
Available options:
SUCCEEDED,
FAILED,
$UNKNOWN
​
lines
object
​
nextBillingDate
object
​
note
string
​
originOrder
object
​
status
enum<string>
Available options:
ACTIVE,
PAUSED,
CANCELLED,
EXPIRED,
FAILED,
$UNKNOWN
​
updatedAt
object