Skip to content
External APIs
/
/
Update custom attributes...

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

Update delivery interval for a subscription contract

Request

Updates the delivery interval for the specified subscription contract. This endpoint allows external API consumers to change the delivery interval count and type (of type SellingPlanInterval) used for scheduling deliveries.

The service validates that the contract exists, that the new delivery interval differs from the current setting, and that it meets all business rules.

Authentication is enforced via the X-API-Key header (the 'api_key' parameter is deprecated).

Query
contractIdinteger(int64)required

Contract ID

api_keystring

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

deliveryIntervalCountinteger(int32)required

Delivery Interval Count

deliveryIntervalstringrequired

Delivery Interval Type

Enum"DAY""WEEK""MONTH""YEAR""$UNKNOWN"
Headers
X-API-Keystring
curl -i -X PUT \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-delivery-interval?contractId=0&api_key=string&deliveryIntervalCount=0&deliveryInterval=DAY' \
  -H 'X-API-Key: string'

Responses

Delivery interval 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 custom attributes on a subscription contract

Request

Updates or replaces custom key-value attributes on a subscription contract. These attributes are stored with the subscription and can be used to track custom data, preferences, or metadata that's important for your business processes.

Custom Attributes Overview: Custom attributes are key-value pairs that allow you to store additional information on subscriptions. They are:

  • Visible in the Shopify admin and accessible via API
  • Included in order data when subscription orders are created
  • Preserved across subscription lifecycle events
  • Useful for integrations and custom workflows

Update Modes:

  • Merge Mode (overwriteExistingAttributes=false): Adds new attributes and updates existing ones with matching keys. Other attributes remain unchanged.
  • Replace Mode (overwriteExistingAttributes=true): Completely replaces all existing attributes with the provided list.

Common Use Cases:

  • Store gift messages or special instructions
  • Track referral sources or marketing campaigns
  • Add internal reference numbers or tracking codes
  • Store customer preferences or customization options
  • Integration data for third-party systems

Important Notes:

  • Attribute keys should not conflict with Shopify's reserved attributes
  • Both keys and values are stored as strings
  • Changes are logged in the activity history
  • Invalid discount codes may be automatically removed during update

Authentication: Requires valid X-API-Key header

Query
overwriteExistingAttributesboolean

Merge or replace mode

Default true
api_keystringDeprecated

API Key (Deprecated)

Headers
X-API-Keystringrequired

API Key

Bodyapplication/jsonrequired
subscriptionContractIdinteger(int64)required

The ID of the subscription contract to update

Example: 123456789
customAttributesListArray of objects(OrderNoteAttribute)required

List of custom attributes to set on the subscription contract. Each attribute is a key-value pair that will be stored with the subscription.

customAttributesList[].​keystringrequired

The attribute key. Should be a unique identifier for this attribute. Use descriptive keys like 'gift_message', 'delivery_instructions', etc.

Example: "gift_message"
customAttributesList[].​valuestring

The attribute value. Can be any string value including JSON-encoded data. Set to empty string to clear an attribute.

Example: "Happy Birthday! Enjoy your subscription!"
curl -i -X POST \
  'https://subscription-admin.appstle.com/api/external/v2/update-custom-note-attributes?overwriteExistingAttributes=true&api_key=string' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: string' \
  -d '{
    "subscriptionContractId": 123456789,
    "customAttributesList": [
      {
        "key": "gift_message",
        "value": "Happy Birthday! Enjoy your subscription!"
      }
    ]
  }'

Responses

Attributes successfully updated

Bodyapplication/json
Response
application/json
{
  "message": "Attributes updated successfully"
}

Split or duplicate an existing subscription contract

Request

Creates a new subscription contract by either splitting (moving) or duplicating selected line items from an existing contract. This endpoint allows you to divide a subscription into multiple contracts or create a copy with specific products.

Split vs Duplicate Mode:

  • Split (isSplitContract=true): Moves the selected line items from the original contract to a new contract. The original contract will no longer contain these items.
  • Duplicate (isSplitContract=false): Creates a new contract with copies of the selected line items while keeping them in the original contract.

Important Notes:

  • When splitting, at least one subscription product must remain in the original contract
  • The new contract inherits all settings from the original: customer, payment method, billing/delivery policies, shipping address, and custom attributes
  • Billing schedule is automatically generated for the new contract
  • One-time products and free products don't count towards the minimum product requirement

Use Cases:

  • Split a subscription when customer wants different delivery schedules for different products
  • Create a gift subscription from an existing subscription
  • Separate products for different shipping addresses
  • Duplicate a subscription for testing or backup purposes

Authentication: Requires valid X-API-Key header

Query
contractIdinteger(int64)required

Subscription contract ID

isSplitContractboolean

Split or duplicate mode

Default false
attemptBillingboolean

Attempt billing immediately

Default false
api_keystringDeprecated

API Key (Deprecated)

Headers
X-API-Keystringrequired

API Key

Bodyapplication/jsonrequiredArray [
string
]
curl -i -X POST \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details/split-existing-contract?contractId=0&isSplitContract=false&attemptBilling=false&api_key=string' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: string' \
  -d '[
    "string"
  ]'

Responses

Contract successfully split/duplicated

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/987654321",
  "status": "ACTIVE",
  "nextBillingDate": "2024-02-15T00:00:00Z",
  "originOrder": {
    "id": "gid://shopify/Order/123456789"
  },
  "customer": {
    "id": "gid://shopify/Customer/111111",
    "email": "customer@example.com"
  },
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "lines": {
    "edges": [ … ]
  },
  "customAttributes": [
    { … },
    { … }
  ]
}

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

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