Subscription Management

Create a new subscription contract

Creates a new subscription contract for a customer with specified products, billing frequency, and delivery details. This endpoint allows you to programmatically create subscriptions with custom pricing, delivery schedules, and multiple line items. The subscription will be created in Shopify and synchronized with the Appstle system. **Important Notes:** - Customer must have at least one valid payment method - If paymentMethodId is not provided, the default payment method will be used - If delivery interval is not specified, it defaults to the billing interval - Custom pricing policies can be applied per line item - All monetary values are in the store's base currency unless currencyCode is specified - CustomAttributes and line item customAttributes use Shopify's AttributeInput format: {"key": "string", "value": "string"} **Pricing Policy Types:** - SELLING_PLAN_PRICING_POLICY: Uses the default pricing from the selling plan - CUSTOM_PRICING_POLICY: Allows custom discount cycles defined in pricingPolicy array - NO_PRICING_POLICY: Uses the base price without any discounts **Authentication:** Requires valid X-API-Key header

POST

api

external

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",
          "freeProductImage": "https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg",
          "freeProductTitle": "Ceramic Mug",
          "freeProducts": [
            {
              "freeProductHandle": "free-gift-product",
              "freeProductImage": "https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg",
              "freeProductTitle": "Ceramic Mug",
              "freeVariantId": 42549172011164
            }
          ],
          "freeVariantId": 42549172011164,
          "preventDuplicationFreeProduct": true,
          "repeatingCycle": true,
          "repeatingNumberOfCycle": 6,
          "tierRole": "<string>",
          "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",
                    "freeProductImage": "https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg",
                    "freeProductTitle": "Ceramic Mug",
                    "freeProducts": [
                        {
                            "freeProductHandle": "free-gift-product",
                            "freeProductImage": "https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg",
                            "freeProductTitle": "Ceramic Mug",
                            "freeVariantId": 42549172011164
                        }
                    ],
                    "freeVariantId": 42549172011164,
                    "preventDuplicationFreeProduct": True,
                    "repeatingCycle": True,
                    "repeatingNumberOfCycle": 6,
                    "tierRole": "<string>",
                    "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',
            freeProductImage: 'https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg',
            freeProductTitle: 'Ceramic Mug',
            freeProducts: [
              {
                freeProductHandle: 'free-gift-product',
                freeProductImage: 'https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg',
                freeProductTitle: 'Ceramic Mug',
                freeVariantId: 42549172011164
              }
            ],
            freeVariantId: 42549172011164,
            preventDuplicationFreeProduct: true,
            repeatingCycle: true,
            repeatingNumberOfCycle: 6,
            tierRole: '<string>',
            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',
            freeProductImage: 'https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg',
            freeProductTitle: 'Ceramic Mug',
            freeProducts: [
              {
                freeProductHandle: 'free-gift-product',
                freeProductImage: 'https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg',
                freeProductTitle: 'Ceramic Mug',
                freeVariantId: 42549172011164
              }
            ],
            freeVariantId: 42549172011164,
            preventDuplicationFreeProduct: true,
            repeatingCycle: true,
            repeatingNumberOfCycle: 6,
            tierRole: '<string>',
            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',
                                                                'freeProductImage' => 'https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg',
                                                                'freeProductTitle' => 'Ceramic Mug',
                                                                'freeProducts' => [
                                                                                                                                [
                                                                                                                                                                                                                                                                'freeProductHandle' => 'free-gift-product',
                                                                                                                                                                                                                                                                'freeProductImage' => 'https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg',
                                                                                                                                                                                                                                                                'freeProductTitle' => 'Ceramic Mug',
                                                                                                                                                                                                                                                                'freeVariantId' => 42549172011164
                                                                                                                                ]
                                                                ],
                                                                'freeVariantId' => 42549172011164,
                                                                'preventDuplicationFreeProduct' => true,
                                                                'repeatingCycle' => true,
                                                                'repeatingNumberOfCycle' => 6,
                                                                'tierRole' => '<string>',
                                                                '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          \"freeProductImage\": \"https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg\",\n          \"freeProductTitle\": \"Ceramic Mug\",\n          \"freeProducts\": [\n            {\n              \"freeProductHandle\": \"free-gift-product\",\n              \"freeProductImage\": \"https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg\",\n              \"freeProductTitle\": \"Ceramic Mug\",\n              \"freeVariantId\": 42549172011164\n            }\n          ],\n          \"freeVariantId\": 42549172011164,\n          \"preventDuplicationFreeProduct\": true,\n          \"repeatingCycle\": true,\n          \"repeatingNumberOfCycle\": 6,\n          \"tierRole\": \"<string>\",\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          \"freeProductImage\": \"https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg\",\n          \"freeProductTitle\": \"Ceramic Mug\",\n          \"freeProducts\": [\n            {\n              \"freeProductHandle\": \"free-gift-product\",\n              \"freeProductImage\": \"https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg\",\n              \"freeProductTitle\": \"Ceramic Mug\",\n              \"freeVariantId\": 42549172011164\n            }\n          ],\n          \"freeVariantId\": 42549172011164,\n          \"preventDuplicationFreeProduct\": true,\n          \"repeatingCycle\": true,\n          \"repeatingNumberOfCycle\": 6,\n          \"tierRole\": \"<string>\",\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

Show child attributes

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

Show child attributes

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"

locationId

string

Shopify location ID used for local pickup. Required when methodType is PICK_UP

Example:

"gid://shopify/Location/123456789"

maxCycles

integer<int32>

Maximum number of billing cycles. Null for unlimited

Required range: x >= 1

Example:

12

methodType

enum<string>

default:SHIPPING

Delivery method. LOCAL requires deliveryPhone, PICK_UP requires locationId

Available options:

SHIPPING,

LOCAL,

PICK_UP

Example:

"SHIPPING"

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

Show child attributes

billingPolicy

object

Show child attributes

createdAt

object

customAttributes

object[]

Show child attributes

customer

object

Show child attributes

customerPaymentMethod

object

Show child attributes

deliveryMethod

object

Show child attributes

deliveryPolicy

object

Show child attributes

deliveryPrice

object

Show child attributes

discounts

object

Show child attributes

get__typename

string

lastPaymentStatus

enum<string>

Available options:

SUCCEEDED,

FAILED,

$UNKNOWN

lines

object

Show child attributes

nextBillingDate

object

note

string

originOrder

object

Show child attributes

status

enum<string>

Available options:

ACTIVE,

PAUSED,

CANCELLED,

EXPIRED,

FAILED,

$UNKNOWN

updatedAt

object

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",
          "freeProductImage": "https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg",
          "freeProductTitle": "Ceramic Mug",
          "freeProducts": [
            {
              "freeProductHandle": "free-gift-product",
              "freeProductImage": "https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg",
              "freeProductTitle": "Ceramic Mug",
              "freeVariantId": 42549172011164
            }
          ],
          "freeVariantId": 42549172011164,
          "preventDuplicationFreeProduct": true,
          "repeatingCycle": true,
          "repeatingNumberOfCycle": 6,
          "tierRole": "<string>",
          "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",
                    "freeProductImage": "https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg",
                    "freeProductTitle": "Ceramic Mug",
                    "freeProducts": [
                        {
                            "freeProductHandle": "free-gift-product",
                            "freeProductImage": "https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg",
                            "freeProductTitle": "Ceramic Mug",
                            "freeVariantId": 42549172011164
                        }
                    ],
                    "freeVariantId": 42549172011164,
                    "preventDuplicationFreeProduct": True,
                    "repeatingCycle": True,
                    "repeatingNumberOfCycle": 6,
                    "tierRole": "<string>",
                    "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',
            freeProductImage: 'https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg',
            freeProductTitle: 'Ceramic Mug',
            freeProducts: [
              {
                freeProductHandle: 'free-gift-product',
                freeProductImage: 'https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg',
                freeProductTitle: 'Ceramic Mug',
                freeVariantId: 42549172011164
              }
            ],
            freeVariantId: 42549172011164,
            preventDuplicationFreeProduct: true,
            repeatingCycle: true,
            repeatingNumberOfCycle: 6,
            tierRole: '<string>',
            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',
            freeProductImage: 'https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg',
            freeProductTitle: 'Ceramic Mug',
            freeProducts: [
              {
                freeProductHandle: 'free-gift-product',
                freeProductImage: 'https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg',
                freeProductTitle: 'Ceramic Mug',
                freeVariantId: 42549172011164
              }
            ],
            freeVariantId: 42549172011164,
            preventDuplicationFreeProduct: true,
            repeatingCycle: true,
            repeatingNumberOfCycle: 6,
            tierRole: '<string>',
            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',
                                                                'freeProductImage' => 'https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg',
                                                                'freeProductTitle' => 'Ceramic Mug',
                                                                'freeProducts' => [
                                                                                                                                [
                                                                                                                                                                                                                                                                'freeProductHandle' => 'free-gift-product',
                                                                                                                                                                                                                                                                'freeProductImage' => 'https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg',
                                                                                                                                                                                                                                                                'freeProductTitle' => 'Ceramic Mug',
                                                                                                                                                                                                                                                                'freeVariantId' => 42549172011164
                                                                                                                                ]
                                                                ],
                                                                'freeVariantId' => 42549172011164,
                                                                'preventDuplicationFreeProduct' => true,
                                                                'repeatingCycle' => true,
                                                                'repeatingNumberOfCycle' => 6,
                                                                'tierRole' => '<string>',
                                                                '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          \"freeProductImage\": \"https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg\",\n          \"freeProductTitle\": \"Ceramic Mug\",\n          \"freeProducts\": [\n            {\n              \"freeProductHandle\": \"free-gift-product\",\n              \"freeProductImage\": \"https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg\",\n              \"freeProductTitle\": \"Ceramic Mug\",\n              \"freeVariantId\": 42549172011164\n            }\n          ],\n          \"freeVariantId\": 42549172011164,\n          \"preventDuplicationFreeProduct\": true,\n          \"repeatingCycle\": true,\n          \"repeatingNumberOfCycle\": 6,\n          \"tierRole\": \"<string>\",\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          \"freeProductImage\": \"https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg\",\n          \"freeProductTitle\": \"Ceramic Mug\",\n          \"freeProducts\": [\n            {\n              \"freeProductHandle\": \"free-gift-product\",\n              \"freeProductImage\": \"https://cdn.shopify.com/s/files/1/0000/0000/products/mug.jpg\",\n              \"freeProductTitle\": \"Ceramic Mug\",\n              \"freeVariantId\": 42549172011164\n            }\n          ],\n          \"freeVariantId\": 42549172011164,\n          \"preventDuplicationFreeProduct\": true,\n          \"repeatingCycle\": true,\n          \"repeatingNumberOfCycle\": 6,\n          \"tierRole\": \"<string>\",\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"
}

Get Started

Guides

Partner Integration

Webhooks

Admin API

Storefront API

Resources

Create a new subscription contract

Headers

Query Parameters

Body

Response