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. <details> <summary>**Full behavior, validation rules, and side effects**</summary> **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 </details>

POST /api/external/v2/subscription-contract-details/create-subscription-contract

Create a new subscription contract

cURL

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
        }
      ]
    }
  ]
}
'

201

Success Response

{
  "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": "[e-mail]",
    "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"
            }
          }
        }
      }
    ]
  }
}

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

Show child attributes

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:

"[phone]"

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

Show child attributes

Example:

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

Response

201

application/json

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

Show child attributes

lastPaymentStatus · enum<string>

Available options: SUCCEEDED, FAILED, $UNKNOWN

billingPolicy · object

Show child attributes

deliveryPolicy · object

Show child attributes

lines · object

Show child attributes

customerPaymentMethod · object

Show child attributes

deliveryMethod · object

Show child attributes

originOrder · object

Show child attributes

customer · object

Show child attributes

discounts · object

Show child attributes

note · string

customAttributes · object[]

Show child attributes

billingAttempts · object

Show child attributes