Skip to content
External APIs
/
/
Update subscription billi...

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

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

Update next billing date for a subscription contract

Request

Reschedules the next billing date for an active subscription contract. This endpoint allows you to change when the next order will be created and processed.

Key Features:

  • Updates the next billing date to the specified date
  • Optionally reschedules all future orders based on the new date
  • Syncs the updated date to Shopify
  • Sends confirmation email to customer

The rescheduleFutureOrder Parameter:

  • true (default): Updates the next billing date AND recalculates all future queued orders based on the new date. Use this to shift the entire billing schedule.
  • false: Only updates the next billing date. Other queued orders remain unchanged. Use this for one-time date adjustments.

Important Notes:

  • The new date must be in the future (with 10 minute grace period)
  • Date is validated against the shop's timezone
  • If anchor days are configured, future orders may align to those anchors

Process Flow:

  1. Validates the contract exists and belongs to the shop
  2. Validates the new date is not in the past
  3. Updates the billing attempt to the new date
  4. Syncs the updated nextBillingDate to Shopify
  5. If rescheduleFutureOrder=true, regenerates the queue from the new date
  6. Sends confirmation email to customer
  7. Records activity log entry

Date Format:

  • Must be ISO 8601 format with timezone
  • Examples: 2024-03-15T12:00:00Z, 2024-03-15T12:00:00+05:30
  • URL encode the date when passing as query parameter

Timezone Handling:

  • The provided date is used as-is for the billing attempt
  • Validation (past date check) uses the shop's configured timezone
  • All dates in the response are in UTC (Z suffix)

Date Restrictions (Customer Portal Only): When called from customer portal context:

  • Minimum days from today (skipDaysFromCurrentDate setting)
  • Maximum days from today (billingDateRestrictToDays setting)
  • External API calls bypass these restrictions

Authentication: Requires valid X-API-Key header

Query
contractIdinteger(int64)>= 1required

Subscription contract ID to update

Example: contractId=123456789
rescheduleFutureOrderboolean

If true (or value not provided), next billing date will be changed and also schedule for future upcoming orders will be changed based on new updated billing date. If false, then only next billing date will be changed, but the schedule for future upcoming orders will not change.

Default true
Example: rescheduleFutureOrder=true
nextBillingDatestring(date-time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d...required

New billing date in ISO 8601 format with timezone. The date must be in the future and may be subject to merchant-configured restrictions. Common formats:

  • UTC: 2024-03-15T12:00:00Z
  • With offset: 2024-03-15T12:00:00+05:30
  • With timezone: 2024-03-15T12:00:00[America/New_York]

The system will convert the date to the shop's timezone for validation.

Example: nextBillingDate=2024-03-15T12:00:00Z
api_keystringDeprecated

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

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-billing-date?contractId=123456789&rescheduleFutureOrder=true&nextBillingDate=2024-03-15T12%3A00%3A00Z&api_key=string' \
  -H 'X-API-Key: sk_live_1234567890abcdef'

Responses

Billing date successfully updated. The response contains the updated subscription contract from Shopify with the new nextBillingDate.

Headers
X-Application-Contextstring

Application context with alert message

Example: "appname:Subscription Updated:"
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
{
  "__typename": "SubscriptionContract",
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-03-15T12:00:00Z",
  "updatedAt": "2024-02-15T10:30:00Z",
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "customer": {
    "email": "customer@example.com",
    "displayName": "John Doe"
  }
}

Update subscription billing attempt

Request

Updates an existing subscription billing attempt. This endpoint allows modification of billing attempt details such as billing date, order note, and other attributes.

Important Notes:

  • Only QUEUED billing attempts can be updated
  • Cannot update attempts that are already processed or failed
  • Billing attempt must belong to the authenticated shop

Authentication: Requires valid X-API-Key header

Query
api_keystring

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

Headers
X-API-Keystring
Bodyapplication/jsonrequired
idinteger(int64)
shopstringrequired
billingAttemptIdstring
statusstring
Enum"SUCCESS""FAILURE""REQUESTING""PROGRESS""QUEUED""SKIPPED""SOCIAL_CONNECTION_NULL""CONTRACT_CANCELLED""CONTRACT_ENDED""CONTRACT_PAUSED"
billingDatestring(date-time)
contractIdinteger(int64)
attemptCountinteger(int32)
attemptTimestring(date-time)
graphOrderIdstring
orderIdinteger(int64)
orderAmountnumber(double)
orderNamestring
retryingNeededbooleanrequired
transactionFailedEmailSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED"
upcomingOrderEmailSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""STOP_FROM_CONTRACT""CONTRACT_PAUSED"
applyUsageChargeboolean
recurringChargeIdinteger(int64)
transactionRatenumber(double)
usageChargeStatusstring
Enum"SUCCESS""FAILED""TO_BE_TRIED"
transactionFailedSmsSentStatusstring
Enum"SENT""UNSENT""FAILED""SMS_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""PHONE_NUMBER_EMPTY"
upcomingOrderSmsSentStatusstring
Enum"SENT""UNSENT""FAILED""SMS_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""STOP_FROM_CONTRACT""CONTRACT_PAUSED""PHONE_NUMBER_EMPTY"
billingAttemptResponseMessagestring
progressAttemptCountinteger(int32)
orderNotestring
variantListArray of objects(VariantQuantity)
securityChallengeSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CONTRACT_CANCELLED"
orderAmountUSDnumber(double)
orderCancelReasonstring
Enum"CUSTOMER""DECLINED""FRAUD""INVENTORY""STAFF""OTHER""$UNKNOWN"
orderCancelledAtstring(date-time)
orderClosedboolean
orderClosedAtstring(date-time)
orderConfirmedboolean
orderDisplayFinancialStatusstring
Enum"PENDING""AUTHORIZED""PARTIALLY_PAID""PARTIALLY_REFUNDED""VOIDED""PAID""REFUNDED""EXPIRED""$UNKNOWN"
orderDisplayFulfillmentStatusstring
Enum"UNFULFILLED""PARTIALLY_FULFILLED""FULFILLED""RESTOCKED""PENDING_FULFILLMENT""OPEN""IN_PROGRESS""ON_HOLD""SCHEDULED""REQUEST_DECLINED"
orderProcessedAtstring(date-time)
lastShippingUpdatedAtstring(date-time)
inventorySkippedAttemptCountinteger(int32)
inventorySkippedRetryingNeededboolean
orderAttributesArray of objects(AttributeInfo)
partialLinesSkippedstring
Enum"INVENTORY_MANAGEMENT""MANUAL"
orderAmountContractCurrencynumber(double)
curl -i -X PUT \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts?api_key=string' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: string' \
  -d '{
    "id": 0,
    "shop": "string",
    "billingAttemptId": "string",
    "status": "SUCCESS",
    "billingDate": "2019-08-24T14:15:22Z",
    "contractId": 0,
    "attemptCount": 0,
    "attemptTime": "2019-08-24T14:15:22Z",
    "graphOrderId": "string",
    "orderId": 0,
    "orderAmount": 0.1,
    "orderName": "string",
    "retryingNeeded": true,
    "transactionFailedEmailSentStatus": "SENT",
    "upcomingOrderEmailSentStatus": "SENT",
    "applyUsageCharge": true,
    "recurringChargeId": 0,
    "transactionRate": 0.1,
    "usageChargeStatus": "SUCCESS",
    "transactionFailedSmsSentStatus": "SENT",
    "upcomingOrderSmsSentStatus": "SENT",
    "billingAttemptResponseMessage": "string",
    "progressAttemptCount": 0,
    "orderNote": "string",
    "variantList": [
      {
        "variantId": 0,
        "quantity": 0,
        "title": "string",
        "image": "string",
        "productTitle": "string",
        "productId": "string",
        "variantTitle": "string",
        "swapId": 0
      }
    ],
    "securityChallengeSentStatus": "SENT",
    "orderAmountUSD": 0.1,
    "orderCancelReason": "CUSTOMER",
    "orderCancelledAt": "2019-08-24T14:15:22Z",
    "orderClosed": true,
    "orderClosedAt": "2019-08-24T14:15:22Z",
    "orderConfirmed": true,
    "orderDisplayFinancialStatus": "PENDING",
    "orderDisplayFulfillmentStatus": "UNFULFILLED",
    "orderProcessedAt": "2019-08-24T14:15:22Z",
    "lastShippingUpdatedAt": "2019-08-24T14:15:22Z",
    "inventorySkippedAttemptCount": 0,
    "inventorySkippedRetryingNeeded": true,
    "orderAttributes": [
      {
        "key": "string",
        "value": "string"
      }
    ],
    "partialLinesSkipped": "INVENTORY_MANAGEMENT",
    "orderAmountContractCurrency": 0.1
  }'

Responses

Billing attempt successfully updated

Bodyapplication/json
idinteger(int64)
shopstringrequired
billingAttemptIdstring
statusstring
Enum"SUCCESS""FAILURE""REQUESTING""PROGRESS""QUEUED""SKIPPED""SOCIAL_CONNECTION_NULL""CONTRACT_CANCELLED""CONTRACT_ENDED""CONTRACT_PAUSED"
billingDatestring(date-time)
contractIdinteger(int64)
attemptCountinteger(int32)
attemptTimestring(date-time)
graphOrderIdstring
orderIdinteger(int64)
orderAmountnumber(double)
orderNamestring
retryingNeededbooleanrequired
transactionFailedEmailSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED"
upcomingOrderEmailSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""STOP_FROM_CONTRACT""CONTRACT_PAUSED"
applyUsageChargeboolean
recurringChargeIdinteger(int64)
transactionRatenumber(double)
usageChargeStatusstring
Enum"SUCCESS""FAILED""TO_BE_TRIED"
transactionFailedSmsSentStatusstring
Enum"SENT""UNSENT""FAILED""SMS_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""PHONE_NUMBER_EMPTY"
upcomingOrderSmsSentStatusstring
Enum"SENT""UNSENT""FAILED""SMS_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""STOP_FROM_CONTRACT""CONTRACT_PAUSED""PHONE_NUMBER_EMPTY"
billingAttemptResponseMessagestring
progressAttemptCountinteger(int32)
orderNotestring
variantListArray of objects(VariantQuantity)
securityChallengeSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CONTRACT_CANCELLED"
orderAmountUSDnumber(double)
orderCancelReasonstring
Enum"CUSTOMER""DECLINED""FRAUD""INVENTORY""STAFF""OTHER""$UNKNOWN"
orderCancelledAtstring(date-time)
orderClosedboolean
orderClosedAtstring(date-time)
orderConfirmedboolean
orderDisplayFinancialStatusstring
Enum"PENDING""AUTHORIZED""PARTIALLY_PAID""PARTIALLY_REFUNDED""VOIDED""PAID""REFUNDED""EXPIRED""$UNKNOWN"
orderDisplayFulfillmentStatusstring
Enum"UNFULFILLED""PARTIALLY_FULFILLED""FULFILLED""RESTOCKED""PENDING_FULFILLMENT""OPEN""IN_PROGRESS""ON_HOLD""SCHEDULED""REQUEST_DECLINED"
orderProcessedAtstring(date-time)
lastShippingUpdatedAtstring(date-time)
inventorySkippedAttemptCountinteger(int32)
inventorySkippedRetryingNeededboolean
orderAttributesArray of objects(AttributeInfo)
partialLinesSkippedstring
Enum"INVENTORY_MANAGEMENT""MANUAL"
orderAmountContractCurrencynumber(double)
Response
application/json
{
  "id": 0,
  "shop": "string",
  "billingAttemptId": "string",
  "status": "SUCCESS",
  "billingDate": "2019-08-24T14:15:22Z",
  "contractId": 0,
  "attemptCount": 0,
  "attemptTime": "2019-08-24T14:15:22Z",
  "graphOrderId": "string",
  "orderId": 0,
  "orderAmount": 0.1,
  "orderName": "string",
  "retryingNeeded": true,
  "transactionFailedEmailSentStatus": "SENT",
  "upcomingOrderEmailSentStatus": "SENT",
  "applyUsageCharge": true,
  "recurringChargeId": 0,
  "transactionRate": 0.1,
  "usageChargeStatus": "SUCCESS",
  "transactionFailedSmsSentStatus": "SENT",
  "upcomingOrderSmsSentStatus": "SENT",
  "billingAttemptResponseMessage": "string",
  "progressAttemptCount": 0,
  "orderNote": "string",
  "variantList": [
    { … }
  ],
  "securityChallengeSentStatus": "SENT",
  "orderAmountUSD": 0.1,
  "orderCancelReason": "CUSTOMER",
  "orderCancelledAt": "2019-08-24T14:15:22Z",
  "orderClosed": true,
  "orderClosedAt": "2019-08-24T14:15:22Z",
  "orderConfirmed": true,
  "orderDisplayFinancialStatus": "PENDING",
  "orderDisplayFulfillmentStatus": "UNFULFILLED",
  "orderProcessedAt": "2019-08-24T14:15:22Z",
  "lastShippingUpdatedAt": "2019-08-24T14:15:22Z",
  "inventorySkippedAttemptCount": 0,
  "inventorySkippedRetryingNeeded": true,
  "orderAttributes": [
    { … }
  ],
  "partialLinesSkipped": "INVENTORY_MANAGEMENT",
  "orderAmountContractCurrency": 0.1
}

Unskip a previously skipped order

Request

Reverses a skip action on a billing attempt. The order will be restored to QUEUED status and will be processed on its scheduled date.

Important Notes:

  • Only works on billing attempts with SKIPPED status
  • Must be done before the scheduled billing date
  • Cannot unskip after the billing date has passed
  • Activity logs are created for audit trail

Use Cases:

  • Customer changes their mind about skipping
  • Correct accidental skip actions
  • Restore delivery after resolving temporary issue

Authentication: Requires valid X-API-Key header

Path
idinteger(int64)required

Billing Attempt ID

Query
api_keystring

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

subscriptionContractIdinteger(int64)

Subscription Contract ID

Headers
X-API-Keystring
curl -i -X PUT \
  'https://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/unskip-order/{id}?api_key=string&subscriptionContractId=0' \
  -H 'X-API-Key: string'

Responses

Order successfully unskipped

Bodyapplication/json
idinteger(int64)
shopstringrequired
billingAttemptIdstring
statusstring
Enum"SUCCESS""FAILURE""REQUESTING""PROGRESS""QUEUED""SKIPPED""SOCIAL_CONNECTION_NULL""CONTRACT_CANCELLED""CONTRACT_ENDED""CONTRACT_PAUSED"
billingDatestring(date-time)
contractIdinteger(int64)
attemptCountinteger(int32)
attemptTimestring(date-time)
graphOrderIdstring
orderIdinteger(int64)
orderAmountnumber(double)
orderNamestring
retryingNeededbooleanrequired
transactionFailedEmailSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED"
upcomingOrderEmailSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""STOP_FROM_CONTRACT""CONTRACT_PAUSED"
applyUsageChargeboolean
recurringChargeIdinteger(int64)
transactionRatenumber(double)
usageChargeStatusstring
Enum"SUCCESS""FAILED""TO_BE_TRIED"
transactionFailedSmsSentStatusstring
Enum"SENT""UNSENT""FAILED""SMS_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""PHONE_NUMBER_EMPTY"
upcomingOrderSmsSentStatusstring
Enum"SENT""UNSENT""FAILED""SMS_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""STOP_FROM_CONTRACT""CONTRACT_PAUSED""PHONE_NUMBER_EMPTY"
billingAttemptResponseMessagestring
progressAttemptCountinteger(int32)
orderNotestring
variantListArray of objects(VariantQuantity)
securityChallengeSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CONTRACT_CANCELLED"
orderAmountUSDnumber(double)
orderCancelReasonstring
Enum"CUSTOMER""DECLINED""FRAUD""INVENTORY""STAFF""OTHER""$UNKNOWN"
orderCancelledAtstring(date-time)
orderClosedboolean
orderClosedAtstring(date-time)
orderConfirmedboolean
orderDisplayFinancialStatusstring
Enum"PENDING""AUTHORIZED""PARTIALLY_PAID""PARTIALLY_REFUNDED""VOIDED""PAID""REFUNDED""EXPIRED""$UNKNOWN"
orderDisplayFulfillmentStatusstring
Enum"UNFULFILLED""PARTIALLY_FULFILLED""FULFILLED""RESTOCKED""PENDING_FULFILLMENT""OPEN""IN_PROGRESS""ON_HOLD""SCHEDULED""REQUEST_DECLINED"
orderProcessedAtstring(date-time)
lastShippingUpdatedAtstring(date-time)
inventorySkippedAttemptCountinteger(int32)
inventorySkippedRetryingNeededboolean
orderAttributesArray of objects(AttributeInfo)
partialLinesSkippedstring
Enum"INVENTORY_MANAGEMENT""MANUAL"
orderAmountContractCurrencynumber(double)
Response
application/json
{
  "id": 0,
  "shop": "string",
  "billingAttemptId": "string",
  "status": "SUCCESS",
  "billingDate": "2019-08-24T14:15:22Z",
  "contractId": 0,
  "attemptCount": 0,
  "attemptTime": "2019-08-24T14:15:22Z",
  "graphOrderId": "string",
  "orderId": 0,
  "orderAmount": 0.1,
  "orderName": "string",
  "retryingNeeded": true,
  "transactionFailedEmailSentStatus": "SENT",
  "upcomingOrderEmailSentStatus": "SENT",
  "applyUsageCharge": true,
  "recurringChargeId": 0,
  "transactionRate": 0.1,
  "usageChargeStatus": "SUCCESS",
  "transactionFailedSmsSentStatus": "SENT",
  "upcomingOrderSmsSentStatus": "SENT",
  "billingAttemptResponseMessage": "string",
  "progressAttemptCount": 0,
  "orderNote": "string",
  "variantList": [
    { … }
  ],
  "securityChallengeSentStatus": "SENT",
  "orderAmountUSD": 0.1,
  "orderCancelReason": "CUSTOMER",
  "orderCancelledAt": "2019-08-24T14:15:22Z",
  "orderClosed": true,
  "orderClosedAt": "2019-08-24T14:15:22Z",
  "orderConfirmed": true,
  "orderDisplayFinancialStatus": "PENDING",
  "orderDisplayFulfillmentStatus": "UNFULFILLED",
  "orderProcessedAt": "2019-08-24T14:15:22Z",
  "lastShippingUpdatedAt": "2019-08-24T14:15:22Z",
  "inventorySkippedAttemptCount": 0,
  "inventorySkippedRetryingNeeded": true,
  "orderAttributes": [
    { … }
  ],
  "partialLinesSkipped": "INVENTORY_MANAGEMENT",
  "orderAmountContractCurrency": 0.1
}

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