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 '
{
  "customerId": "987654321",
  "status": "ACTIVE",
  "nextBillingDate": "2024-02-01T00:00:00Z",
  "billingIntervalType": "MONTH",
  "billingIntervalCount": 1,
  "deliveryAddress1": "123 Main St",
  "deliveryCity": "New York",
  "deliveryCountryCode": "US",
  "lines": [
    {
      "quantity": 2,
      "variantId": "42549172011164",
      "productId": "7234567890123",
      "sellingPlanId": "gid://shopify/SellingPlan/123456",
      "currentPrice": 25.99,
      "unitPrice": 29.99,
      "customAttributes": [
        {
          "key": "engraving",
          "value": "Happy Birthday"
        }
      ],
      "linePricingPolicy": "SELLING_PLAN_PRICING_POLICY",
      "pricingPolicy": [
        {
          "afterCycle": 3,
          "discountType": "PERCENTAGE",
          "value": 10,
          "freeVariantId": 42549172011164,
          "freeProductHandle": "free-gift-product",
          "repeatingCycle": true,
          "repeatingNumberOfCycle": 6,
          "preventDuplicationFreeProduct": true
        }
      ]
    }
  ]
}
'
{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-02-01T00:00:00Z",
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1,
    "minCycles": 3,
    "maxCycles": 12
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "customer@example.com",
    "firstName": "John",
    "lastName": "Doe"
  },
  "deliveryPrice": {
    "amount": "5.99",
    "currencyCode": "USD"
  },
  "lines": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 2,
          "variantId": "gid://shopify/ProductVariant/42549172011164",
          "currentPrice": {
            "amount": "25.99",
            "currencyCode": "USD"
          },
          "pricingPolicy": {
            "basePrice": {
              "amount": "29.99",
              "currencyCode": "USD"
            }
          }
        }
      }
    ]
  }
}

Documentation Index

Fetch the complete documentation index at: https://appstleinc-aeca3e0a.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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

​
customerId
string
required

Shopify customer ID (numeric ID without gid prefix)

Example:

"987654321"

​
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"

​
nextBillingDate
string<date-time>
required

Date when the next billing/order will occur

Example:

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

​
billingIntervalType
enum<string>
required

Billing frequency interval type

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

"MONTH"

​
billingIntervalCount
integer<int32>
required

Number of intervals between billings

Required range: x >= 1
Example:

1

​
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

​
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"

​
createWithoutPaymentMethod
boolean
default:false

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

Example:

false

​
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

​
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

​
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"

​
deliveryIntervalCount
integer<int32>

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

Required range: x >= 1
Example:

1

​
deliveryFirstName
string

Delivery address first name

Example:

"John"

​
deliveryLastName
string

Delivery address last name

Example:

"Doe"

​
deliveryAddress2
string

Delivery address line 2

Example:

"Apt 4B"

​
deliveryProvinceCode
string

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

Example:

"NY"

​
deliveryZip
string

Delivery address postal/zip code

Example:

"10001"

​
deliveryPhone
string

Delivery phone number

Example:

"+1234567890"

​
deliveryPriceAmount
number<double>

Fixed delivery price amount in store currency

Example:

5.99

​
currencyCode
string

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

Example:

"USD"

​
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

​
customAttributes
object[]

Custom attributes to attach to the subscription contract

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

Response

Subscription contract successfully created

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