Skip to content
/Subscription Contracts

External APIs (0.0.1)

Comprehensive API documentation for managing subscriptions, payments, and related operations. These APIs allow you to programmatically manage subscription lifecycles, handle payments, configure products, and integrate subscription functionality into your applications.

Download OpenAPI description
external-api-swagger.json
external-api-swagger.yaml
Languages
Servers
https://subscription-admin.appstle.com

Subscription Management

Core APIs for managing the complete subscription lifecycle including creation, updates, pausing, resuming, and cancellation of subscriptions.

Operations

Subscription Payments

APIs for managing subscription payment methods, processing payments, handling payment retries, and updating billing information.

Operations

Subscription Contracts

APIs for managing subscription contracts including delivery schedules, pricing, order notes, billing cycles, and shipping addresses.

Operations

Update multiple line item attributes for a subscription contract

Request

Updates custom attributes for multiple line items within a subscription contract. The request body must be a JSON object where each key is a line item identifier (as a String) and each value is a list of AttributeInfo objects containing attribute key/value pairs. For example: { "gid://shopify/SubscriptionLineItem/987654321": [ { "key": "color", "value": "red" }, { "key": "size", "value": "M" } ] }. The service validates that the contract exists and that each specified line item is eligible for update. Authentication is performed via the X-API-Key header (the 'api_key' parameter is deprecated).

Query
contractIdinteger(int64)required

The unique identifier of the subscription contract

Example: contractId=123456789
api_keystringDeprecated

API Key (Deprecated - Use Header X-API-Key instead)

Headers
X-API-Keystringrequired

API Key for authentication

Bodyapplication/jsonrequired

A JSON object where each key is a line item ID (e.g., "gid://shopify/SubscriptionLineItem/987654321") and each value is a list of AttributeInfo objects containing the attribute key and value. Example: { "gid://shopify/SubscriptionLineItem/987654321": [ { "key": "color", "value": "red" }, { "key": "size", "value": "M" } ] }

property name*Array of objects(AttributeInfo)additional property
curl -i -X PUT \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-multiple-line-item-attributes?contractId=123456789&api_key=string' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: string' \
  -d '{
    "property1": [
      {
        "key": "string",
        "value": "string"
      }
    ],
    "property2": [
      {
        "key": "string",
        "value": "string"
      }
    ]
  }'

Responses

Multiple line item attributes updated successfully

Bodyapplication/json
get__typenamestring
idstring
createdAtobject
updatedAtobject
nextBillingDateobject
statusstring
Enum"ACTIVE""PAUSED""CANCELLED""EXPIRED""FAILED""$UNKNOWN"
deliveryPriceobject(DeliveryPrice)
lastPaymentStatusstring
Enum"SUCCEEDED""FAILED""$UNKNOWN"
billingPolicyobject(BillingPolicy)
deliveryPolicyobject(DeliveryPolicy)
linesobject(Lines)
customerPaymentMethodobject(CustomerPaymentMethod)
deliveryMethodobject(DeliveryMethod)
originOrderobject(OriginOrder)
customerobject(Customer)
discountsobject(Discounts)
notestring
customAttributesArray of objects(CustomAttribute1)
billingAttemptsobject(BillingAttempts)
Response
application/json
{
  "get__typename": "string",
  "id": "string",
  "createdAt": {},
  "updatedAt": {},
  "nextBillingDate": {},
  "status": "ACTIVE",
  "deliveryPrice": {
    "get__typename": "string",
    "amount": {},
    "currencyCode": "USD"
  },
  "lastPaymentStatus": "SUCCEEDED",
  "billingPolicy": {
    "get__typename": "string",
    "interval": "DAY",
    "intervalCount": 0,
    "anchors": [ … ],
    "maxCycles": 0,
    "minCycles": 0
  },
  "deliveryPolicy": {
    "get__typename": "string",
    "interval": "DAY",
    "intervalCount": 0,
    "anchors": [ … ]
  },
  "lines": {
    "get__typename": "string",
    "nodes": [ … ],
    "pageInfo": { … }
  },
  "customerPaymentMethod": {
    "get__typename": "string",
    "id": "string",
    "instrument": { … },
    "revokedAt": {},
    "revokedReason": "AUTHORIZE_NET_GATEWAY_NOT_ENABLED"
  },
  "deliveryMethod": {
    "get__typename": "string"
  },
  "originOrder": {
    "get__typename": "string",
    "id": "string",
    "name": "string",
    "fulfillmentOrders": { … }
  },
  "customer": {
    "get__typename": "string",
    "id": "string",
    "email": "string",
    "displayName": "string",
    "firstName": "string",
    "lastName": "string",
    "phone": "string"
  },
  "discounts": {
    "get__typename": "string",
    "nodes": [ … ],
    "pageInfo": { … }
  },
  "note": "string",
  "customAttributes": [
    { … }
  ],
  "billingAttempts": {
    "get__typename": "string",
    "nodes": [ … ]
  }
}

Update line item attributes for a subscription contract

Request

Updates the custom attributes for a specific line item within a subscription contract. This endpoint accepts a contract ID, a line item ID, and a list of attribute objects (each containing key/value pairs) to update. It uses the underlying service to perform validation (such as contract existence, freeze status, and attribute-based cycle limits) before applying the update. The operation is intended for external API consumers, and authentication is performed via the X-API-Key header. Deprecated api_key parameter is supported for backward compatibility.

Query
contractIdinteger(int64)required

The unique identifier of the subscription contract

Example: contractId=123456789
lineIdstringrequired

The unique identifier of the line item to update

Example: lineId=gid://shopify/SubscriptionLineItem/987654321
api_keystringDeprecated

Deprecated: API key (use X-API-Key header instead)

Headers
X-API-Keystringrequired

API Key for authentication

Bodyapplication/jsonrequiredArray [
keystring
valuestring
]
curl -i -X PUT \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-attributes?contractId=123456789&lineId=gid%3A%2F%2Fshopify%2FSubscriptionLineItem%2F987654321&api_key=string' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: string' \
  -d '[
    {
      "key": "string",
      "value": "string"
    }
  ]'

Responses

Line item attributes updated successfully

Bodyapplication/json
get__typenamestring
idstring
createdAtobject
updatedAtobject
nextBillingDateobject
statusstring
Enum"ACTIVE""PAUSED""CANCELLED""EXPIRED""FAILED""$UNKNOWN"
deliveryPriceobject(DeliveryPrice)
lastPaymentStatusstring
Enum"SUCCEEDED""FAILED""$UNKNOWN"
billingPolicyobject(BillingPolicy)
deliveryPolicyobject(DeliveryPolicy)
linesobject(Lines)
customerPaymentMethodobject(CustomerPaymentMethod)
deliveryMethodobject(DeliveryMethod)
originOrderobject(OriginOrder)
customerobject(Customer)
discountsobject(Discounts)
notestring
customAttributesArray of objects(CustomAttribute1)
billingAttemptsobject(BillingAttempts)
Response
application/json
{
  "get__typename": "string",
  "id": "string",
  "createdAt": {},
  "updatedAt": {},
  "nextBillingDate": {},
  "status": "ACTIVE",
  "deliveryPrice": {
    "get__typename": "string",
    "amount": {},
    "currencyCode": "USD"
  },
  "lastPaymentStatus": "SUCCEEDED",
  "billingPolicy": {
    "get__typename": "string",
    "interval": "DAY",
    "intervalCount": 0,
    "anchors": [ … ],
    "maxCycles": 0,
    "minCycles": 0
  },
  "deliveryPolicy": {
    "get__typename": "string",
    "interval": "DAY",
    "intervalCount": 0,
    "anchors": [ … ]
  },
  "lines": {
    "get__typename": "string",
    "nodes": [ … ],
    "pageInfo": { … }
  },
  "customerPaymentMethod": {
    "get__typename": "string",
    "id": "string",
    "instrument": { … },
    "revokedAt": {},
    "revokedReason": "AUTHORIZE_NET_GATEWAY_NOT_ENABLED"
  },
  "deliveryMethod": {
    "get__typename": "string"
  },
  "originOrder": {
    "get__typename": "string",
    "id": "string",
    "name": "string",
    "fulfillmentOrders": { … }
  },
  "customer": {
    "get__typename": "string",
    "id": "string",
    "email": "string",
    "displayName": "string",
    "firstName": "string",
    "lastName": "string",
    "phone": "string"
  },
  "discounts": {
    "get__typename": "string",
    "nodes": [ … ],
    "pageInfo": { … }
  },
  "note": "string",
  "customAttributes": [
    { … }
  ],
  "billingAttempts": {
    "get__typename": "string",
    "nodes": [ … ]
  }
}

Update Subscription contract frequency by selling plan

Request

Query
contractIdinteger(int64)>= 1required

Subscription contract ID to update. Provide the numeric ID without the gid:// prefix

Example: contractId=123456789
sellingPlanIdinteger(int64)>= 1required

The unique identifier of the new selling plan. Provide the numeric ID without gid:// prefix.

Example: sellingPlanId=56789
Headers
X-API-Keystringrequired

API Key for authentication

Example: sk_live_1234567890abcdef
curl -i -X PUT \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-frequency-by-selling-plan?contractId=123456789&sellingPlanId=56789' \
  -H 'X-API-Key: sk_live_1234567890abcdef'

Responses

Subscription contract frequency updated successfully

Bodyapplication/json
get__typenamestring
idstring
createdAtobject
updatedAtobject
nextBillingDateobject
statusstring
Enum"ACTIVE""PAUSED""CANCELLED""EXPIRED""FAILED""$UNKNOWN"
deliveryPriceobject(DeliveryPrice)
lastPaymentStatusstring
Enum"SUCCEEDED""FAILED""$UNKNOWN"
billingPolicyobject(BillingPolicy)
deliveryPolicyobject(DeliveryPolicy)
linesobject(Lines)
customerPaymentMethodobject(CustomerPaymentMethod)
deliveryMethodobject(DeliveryMethod)
originOrderobject(OriginOrder)
customerobject(Customer)
discountsobject(Discounts)
notestring
customAttributesArray of objects(CustomAttribute1)
billingAttemptsobject(BillingAttempts)
Response
application/json
{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2025-08-08T13:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/111111111111",
    "email": "abc@gmail.com",
    "displayName": "abc xyz",
    "firstName": "abc",
    "lastName": "xyz"
  },
  "billingPolicy": {
    "interval": "DAY",
    "intervalCount": 5,
    "anchors": [],
    "maxCycles": 6,
    "minCycles": 3
  },
  "deliveryPolicy": {
    "interval": "DAY",
    "intervalCount": 5,
    "anchors": []
  },
  "lines": {
    "edges": [ … ]
  },
  "customerPaymentMethod": {
    "id": "gid://shopify/CustomerPaymentMethod/1111111111111111111",
    "instrument": { … }
  },
  "deliveryMethod": {
    "address": { … }
  }
}

Subscription Products

APIs for managing products within subscriptions including adding, removing, updating quantities, and swapping products.

Operations

Billing & Payments

APIs for handling billing operations, payment processing, and financial transactions related to subscriptions.

Operations

Subscription Discounts

APIs for managing discounts and promotional codes applied to subscriptions.

Operations

Subscription One-Time Products

APIs for managing one-time add-on products that can be purchased alongside recurring subscription items.

Operations

Subscription Plans

APIs for managing subscription plans, pricing tiers, and plan configurations.

Operations

Build-a-Box & Bundles

APIs for managing customizable product boxes and bundles where customers can select multiple items.

Operations

Product Catalog

APIs for managing the product catalog including product information, variants, and inventory.

Operations

Operations & Settings

APIs for managing operational settings, configurations, and administrative functions.

Operations

Customer Portal

APIs powering the customer-facing portal where subscribers can manage their own subscriptions.

Operations

Customers

APIs for managing customer information, profiles, and account details.

Operations