> ## Documentation Index
> Fetch the complete documentation index at: https://developers.appstle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Appstle Subscriptions integration guide

> Integrate with Appstle Subscriptions: authentication, base URL, subscription management, product operations, discounts, shipping, past orders, cancellation and pause records, and partner connections.

This guide covers everything you need to build a full integration with Appstle Subscriptions. It assumes you already have an API key — if not, see the [Authentication](https://developers.appstle.com/subscription/authentication.md) page first.

## Base URL

All Admin API endpoints share this base URL:

```
https://subscription-admin.appstle.com/api/external/v2/
```

> [!NOTE]
>
> With a valid API key, a `GET` to a path under `/api/external/` that has no `GET` endpoint returns `404`, whether the path is mistyped or the endpoint takes another method. Its `detail` is `No API endpoint matches this method and path. Check both against the API docs.` A `POST`, `PUT` or `DELETE` to a path that doesn't take that method returns `405` with `Request method 'PUT' not supported` (or `'POST'`, `'DELETE'`). If you get either, check the path and the method against the [API reference](https://developers.appstle.com/subscription-admin-api/subscription-contracts/retrieve-subscription-contracts.md).

## Authentication

Pass your API key in the `X-API-Key` header on every request:

```bash theme={null}
curl -H "X-API-Key: apst_your-api-key-here" \
  "https://subscription-admin.appstle.com/api/external/v2/..."
```

For partner integrations that connect on behalf of multiple merchants, use the [Partner Integration Framework](https://developers.appstle.com/subscription/partner-integration.md). After a merchant approves a **Nonce Handshake** connection, Appstle issues your application a scoped API token for that merchant. Send that token as `X-API-Key`:

```bash theme={null}
curl -H "X-API-Key: apst_scoped-partner-token" \
  "https://subscription-admin.appstle.com/api/external/v2/..."
```

See [Authentication](https://developers.appstle.com/subscription/authentication.md) for merchant API key management and [Partner integration](https://developers.appstle.com/subscription/partner-integration.md) for the complete connection flow.

## Looking up customer subscriptions

### Get all subscriptions for a customer

```bash theme={null}
curl -X GET \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-customers/{customerId}" \
  -H "X-API-Key: YOUR_API_KEY"
```

The response includes active, paused, and cancelled subscriptions along with products, next billing date, shipping address, and delivery method.

### List a customer's contract IDs

Returns the IDs of every subscription contract the customer has, whatever its status. An empty array means the customer has no subscriptions. To know whether one is active, read its `status` with [Get full contract details](#get-full-contract-details).

```bash theme={null}
curl -X GET \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-customers/valid/{customerId}" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Get full contract details

Filter the contract list by the contract's ID. The response is an array. The filter matches part of an ID, so take the entry whose `subscriptionContractId` equals your ID:

```bash theme={null}
curl -X GET \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details?subscriptionContractId={contractId}" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Find the subscription behind an order

The contract list has no order ID filter. To find the contract or contracts for an order, for example when you handle Shopify's `orders/cancelled` webhook, search by the order's name and then check the order ID. Appstle records a new contract shortly after the order is placed, so a search sent as soon as an `orders/create` webhook arrives can come back empty. Search again after a short wait, or act on the [`subscription.created`](https://developers.appstle.com/subscription/webhooks) event instead.

**1. Search by order name**

`orderName` matches part of a name and ignores case, and it matches the name of a contract's first order and of its renewal orders. Encode `#` as `%23`.

```bash theme={null}
curl -X GET \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-contract-details?orderName=%231001" \
  -H "X-API-Key: YOUR_API_KEY"
```

**2. Keep the contracts whose orderId matches**

Because the match is partial, a search for `#100` also returns the contracts of `#1001`, `#1002` and any other order whose name contains it. Compare each result's `orderId` with the ID of the order you are handling. One order can create more than one contract, so expect a list:

```json theme={null}
[
  { "subscriptionContractId": 123456789012, "status": "active", "orderId": 5512345678901, "orderName": "#1001" },
  { "subscriptionContractId": 123456789013, "status": "active", "orderId": 5512345678901, "orderName": "#1001" }
]
```

The example shows only the fields you need: each entry is a full contract. An empty list means no first order or renewal order has a name containing your search. The list is paged: 20 contracts a page unless you set `size`, up to 2000, and `x-total-count` holds the number of matches. When it is larger than `size`, request the next page with the same parameters and `page` set to the next number. Don't follow the URLs in the `link` header: they encode the `#` a second time and search for the wrong text.

**3. For a renewal order, confirm with past orders**

If the search returns contracts but none has your order's ID, the order may be a renewal order. The contract in the result shows its first order: `orderId` and `orderName` belong to the first order, not to the renewal. To confirm a renewal, call [Get order history](#get-order-history) with the contract's ID and look for the renewal's `orderId`. The list also includes the contract's first order, with `id` set to `null`.

```bash theme={null}
curl -X GET \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/past-orders?contractId={contractId}" \
  -H "X-API-Key: YOUR_API_KEY"
```

Every order a subscription creates also carries the contract in its `appstle_subscription` / `details` order metafield: see [Order metafields](https://developers.appstle.com/subscription/metafields-and-tags.md#order-metafields).

### Get upcoming orders

```bash theme={null}
curl -X GET \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/top-orders?contractId={contractId}" \
  -H "X-API-Key: YOUR_API_KEY"
```

## Subscription management

### Cancel a subscription

```bash theme={null}
curl -X DELETE \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts/{contractId}" \
  -H "X-API-Key: YOUR_API_KEY"
```

The optional `cancellationFeedback` and `cancellationNote` query parameters store why the subscription was cancelled. A successful call returns `204 No Content`.

You can retry this call safely. For a subscription that is already cancelled it returns `204` and does nothing, and the customer gets no second cancellation email. If the plan sets a minimum number of billing cycles and the subscription hasn't reached it, the call returns `400`, unless the subscription is in its free trial. The status call below doesn't apply that rule. `title` and `message` hold the store's minimum-cycles message after a `UserGeneratedError:` prefix. The default message is shown here, and a store can change it:

```json theme={null}
{
  "type": "https://appstle.com/problem/problem-with-message",
  "title": "UserGeneratedError:Subscription requires minimum billing iterations of 3 before it can be cancelled.",
  "status": 400,
  "message": "UserGeneratedError:Subscription requires minimum billing iterations of 3 before it can be cancelled.",
  "params": ""
}
```

A `204` doesn't prove the contract existed: an ID that isn't found for your store also returns `204` and does nothing. Read the contract with [Get full contract details](#get-full-contract-details) first when you need to be sure.

> [!NOTE]
>
> The `PUT` endpoints in this guide read their inputs from the **query string**, not from a JSON body. A request that sends them in a body returns `400` with `Required request parameter 'contractId' for method parameter type Long is not present`. The one exception is [Update shipping address](#update-shipping-address), which takes the address as a JSON body.

### Pause a subscription

```bash theme={null}
curl -X PUT \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-status?contractId={contractId}&status=PAUSED" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Resume a subscription

```bash theme={null}
curl -X PUT \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-status?contractId={contractId}&status=ACTIVE" \
  -H "X-API-Key: YOUR_API_KEY"
```

`status` is `ACTIVE`, `PAUSED` or `CANCELLED`, in uppercase: `status=paused` on an active subscription returns `400`. A successful call returns `204 No Content`.

> [!WARNING]
>
> The call doesn't check the subscription's current status. For a cancelled subscription, `status=PAUSED` and `status=ACTIVE` return `204` and move it from `cancelled` to `paused` or `active`, in Appstle and in Shopify. `ACTIVE` also schedules its upcoming orders again, so the customer is charged on the next billing date. Either way, the customer gets the store's pause or resume email, unless the store has turned that email off. Read `status` with [Get full contract details](#get-full-contract-details) first, and only pause or resume subscriptions that are `"active"` or `"paused"`.

Sending the status a subscription already has, such as `status=PAUSED` for a paused subscription, returns `204` and changes nothing. The exception is `status=ACTIVE` on an active prepaid subscription that is due to cancel at the end of its term: the call clears that pending cancellation, so the subscription isn't cancelled when the term ends, and `pendingCancellationDate` goes back to `null`. The call doesn't restore the orders after the term that the cancellation removed, so check [Get upcoming orders](#get-upcoming-orders) afterwards. `status=CANCELLED` cancels at once even when the plan's minimum number of billing cycles hasn't been reached, so use [Cancel a subscription](#cancel-a-subscription) when you want the minimum enforced. A contract ID that isn't one of your store's contracts returns `400` with `Contract does not exist`.

### Resume on a specific date

To resume a paused subscription with its next charge on a date you choose, for example 14 days after its first order is delivered, set the next billing date while the subscription is still paused, then resume it. Make both calls at the moment you resume, and send the second only after the first returns `200`:

```bash theme={null}
# 1. Set the date of the first charge. The subscription stays paused.
curl -X PUT \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-date?contractId={contractId}&nextBillingDate=2027-03-15T00:00:00Z" \
  -H "X-API-Key: YOUR_API_KEY"

# 2. Resume it.
curl -X PUT \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-status?contractId={contractId}&status=ACTIVE" \
  -H "X-API-Key: YOUR_API_KEY"
```

Here is what happens to the date:

* **Setting the date works on a paused subscription.** The first call returns `200` with the contract still `PAUSED` and `nextBillingDate` set to your date.
* **Resuming keeps a date that is still in the future.** The first upcoming order is on your date, and the rest follow at the plan's billing interval.
* **Resuming moves a date that has passed.** The call moves `nextBillingDate` forward to the first date after now on the subscription's billing schedule, so the next charge can be up to one billing interval away. For a monthly plan resumed a few seconds after its date, `nextBillingDate` came back exactly one month later. In this case `status` can still read `paused` for a moment after the `204` before it changes to `active`.
* **A paused subscription's date doesn't wait.** When `nextBillingDate` arrives while the subscription is paused, nothing is charged and Appstle moves `nextBillingDate` on to the next scheduled order. A date you set when you pause is replaced if it arrives before you resume, so set the date at the moment you resume.

Read `nextBillingDate` with [Get full contract details](#get-full-contract-details) after the second call to confirm the date. A subscription on a plan with fixed billing dates can't be rescheduled, so the first call returns `400` for it (see [Reschedule the next billing date](#reschedule-the-next-billing-date)).

### Reschedule the next billing date

```bash theme={null}
curl -X PUT \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-date?contractId={contractId}&nextBillingDate=2027-03-15T00:00:00Z" \
  -H "X-API-Key: YOUR_API_KEY"
```

`nextBillingDate` is an ISO 8601 date with a time zone. URL-encode a `+` in an offset as `%2B`. The date must be in the future: a past date returns `400`. By default Appstle also moves the later orders to follow the new date; send `rescheduleFutureOrder=false` to change only the next one. A successful call returns `200` with the updated contract as Shopify returns it, including its new `nextBillingDate`. The call also works on a paused subscription: the date is saved and the subscription stays paused (see [Resume on a specific date](#resume-on-a-specific-date)). A subscription on a plan with fixed billing dates can't be rescheduled: the call returns `400` with `errorKey` `fixedBillingScheduleRescheduleBlocked` and `UserGeneratedError:Fixed billing schedule subscriptions cannot be rescheduled. The next order date follows the plan's fixed billing dates.`

A successful call also sends the customer the store's **Next Order Date Updated** email (its default subject is "Your next order date has been updated!"). No request parameter skips it, whether `rescheduleFutureOrder` is `true` or `false`. Two store settings in the Appstle Subscriptions app stop it: the email is turned off under **More** → **Notification Settings**, or the subscription is paused and **Disable notifications for paused or canceled subscriptions** is on under **Shop Settings**.

> [!NOTE]
>
> Changing the next billing date needs an Appstle plan that includes it, on top of API access. Stores that choose a paid plan today get it, and the Free plan doesn't include it. A store on a plan without it gets `400` with `errorKey` `permissionDenied` and `UserGeneratedError:Upgrade your plan to modify next billing date.` A store that chose its plan earlier, or is on a custom plan, may not have it: contact [support@appstle.com](mailto:support@appstle.com) to check. The reschedule-order endpoint (`PUT /api/external/v2/subscription-billing-attempts/reschedule-order/{id}`) needs the same permission.

### Update billing frequency

```bash theme={null}
curl -X PUT \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-interval?contractId={contractId}&intervalCount=2&interval=MONTH" \
  -H "X-API-Key: YOUR_API_KEY"
```

`interval` is `DAY`, `WEEK`, `MONTH` or `YEAR`, and `intervalCount` is how many of them pass between orders (1 to 365). A successful call returns `200` with the updated contract.

Depending on the store's settings, changing the frequency recalculates the next billing date, so a date you set earlier with [Reschedule the next billing date](#reschedule-the-next-billing-date) may not be kept. To change both, set the frequency first and the date second, and check `nextBillingDate` in each response.

Changing the billing frequency needs an Appstle plan that includes it. Stores that choose a paid plan today get it, and the Free plan doesn't include it. A store on a plan without it gets `400` with `errorKey` `permissionDenied` and `UserGeneratedError:Upgrade your plan to modify billing interval.` A store that chose its plan earlier, or is on a custom plan, may not have it: contact [support@appstle.com](mailto:support@appstle.com) to check.

### Skip an upcoming order

`{id}` is the `id` of an upcoming order from [Get upcoming orders](#get-upcoming-orders):

```bash theme={null}
curl -X PUT \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/skip-order/{id}" \
  -H "X-API-Key: YOUR_API_KEY"
```

A successful call returns `200` with that upcoming order, and its `status` is now `SKIPPED`. The order no longer appears in the next [upcoming orders](#get-upcoming-orders) response.

## Product management

> [!NOTE]
>
> To protect customers from accidental or fraudulent charges, a store with the charge cap on refuses an API change to a subscription's products, such as adding a product or raising a quantity, when it would raise the subscription's amount to more than 3 times the customer's original order amount (5 times once the subscription has billed 3 times). A subscription with no original order amount on file is capped at 500 USD instead, converted to its currency. New installs have the charge cap on. The call returns `400` with `errorKey` `line_item_escalation_blocked` and a message that starts with `UserGeneratedError:To prevent fraudulent or accidental charges, this change was blocked`. Changes a customer makes in the customer portal aren't subject to this limit. To raise the limit for a store, contact [support@appstle.com](mailto:support@appstle.com).

### Add a product to a subscription

```bash theme={null}
curl -X PUT \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-add-line-item?contractId={contractId}&variantId={variantId}&quantity=1" \
  -H "X-API-Key: YOUR_API_KEY"
```

`variantId` is the Shopify variant ID, with or without the `gid://` prefix. Add `isOneTimeProduct=true` to add the product to the next order only. A successful call returns `200` with the updated contract. Each entry in its `lines.nodes` has an `id` such as `gid://shopify/SubscriptionLine/ae46e632-dfd0-4135-b577-2d0a634042bf`.

### Remove a product from a subscription

```bash theme={null}
curl -X PUT \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-remove-line-item?contractId={contractId}&lineId=gid://shopify/SubscriptionLine/{lineId}" \
  -H "X-API-Key: YOUR_API_KEY"
```

`lineId` is the line's full `gid://` ID, from `lines.nodes[].id`. A successful call returns `200` with the updated contract. Read the IDs with [`GET /subscription-contracts/contract-external/{contractId}`](https://developers.appstle.com/subscription-admin-api/subscription-management/get-raw-shopify-graphql-contract-response).

### Update product quantity

```bash theme={null}
curl -X PUT \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-line-item-quantity?contractId={contractId}&lineId=gid://shopify/SubscriptionLine/{lineId}&quantity=3" \
  -H "X-API-Key: YOUR_API_KEY"
```

A successful call returns `200` with the updated contract.

## Discounts

Applying and removing a discount need an Appstle plan that includes contract price changes. Stores that choose a paid plan today get it, and the Free plan doesn't include it. A store on a plan without it gets `400` with `errorKey` `permissionDenied` and `UserGeneratedError:Upgrade your plan to modify contract price.` A store that chose its plan earlier, or is on a custom plan, may not have it: contact [support@appstle.com](mailto:support@appstle.com) to check.

### Apply a discount code

```bash theme={null}
curl -X PUT \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-apply-discount?contractId={contractId}&discountCode=SAVE10" \
  -H "X-API-Key: YOUR_API_KEY"
```

The code must be one of the store's Shopify discount codes, and its **Purchase type** must include subscriptions. A successful call returns `200` with the updated contract. The new discount is in `discounts.nodes[]`, and each line's `lineDiscountedPrice` shows the price after the discount. This is a trimmed response for a 10 percent code called `SAVE10` on a contract with one line:

```json theme={null}
{
  "__typename": "SubscriptionContract",
  "id": "gid://shopify/SubscriptionContract/1234567890123",
  "status": "ACTIVE",
  "lines": {
    "nodes": [
      {
        "title": "House Blend Coffee",
        "quantity": 1,
        "currentPrice": { "amount": "16.2", "currencyCode": "USD" },
        "lineDiscountedPrice": { "amount": "14.58", "currencyCode": "USD" }
      }
    ]
  },
  "discounts": {
    "nodes": [
      {
        "id": "gid://shopify/SubscriptionManualDiscount/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
        "title": "SAVE10",
        "value": { "percentage": 10 },
        "recurringCycleLimit": 1,
        "targetType": "LINE_ITEM",
        "type": "CODE_DISCOUNT"
      }
    ]
  }
}
```

Keep the discount's `id`: it is the `discountId` you pass to [remove a discount](#remove-a-discount). In this example the code is set in Shopify to apply to one recurring payment, so `recurringCycleLimit` is `1`.

A refused call returns `400`. The body's `errorKey` says why, and its `message` starts with `UserGeneratedError:`. Each item gives the `errorKey`, then the message after that prefix:

* `DISCOUNT_NOT_FOUND`, `Discount code not found`: the code isn't one of the store's Shopify discount codes.
* `DISCOUNT_NOT_ACTIVE`, `This discount code is not currently active`: the discount has expired or hasn't started yet.
* `DISCOUNT_NOT_STARTED`, `This discount code is not yet active`, and `DISCOUNT_EXPIRED`, `This discount code has expired`: the same two cases, found from the discount's start and end dates. The app checks the discount's status first, so you normally get `DISCOUNT_NOT_ACTIVE` instead.
* `USAGE_LIMIT_REACHED`, `This discount code has reached its usage limit`: the discount has used up its total number of uses.
* `NOT_APPLICABLE_TO_SUBSCRIPTIONS`, `This discount code cannot be applied to subscriptions`: the discount's **Purchase type** is **One-time purchase**.
* `ALREADY_USED_BY_CUSTOMER`, `You have already used this discount code`: the discount allows one use per customer, and this contract's customer has used it.
* `CUSTOMER_NOT_ELIGIBLE`, `This discount code is not available for your account`: the discount is limited to specific customers, and this contract's customer isn't one of them.
* `subscriptionTotalAlreadyZero`, `This subscription already has a total price of $0. An additional discount cannot be applied.`: the contract's total is already \$0.
* `updateError`: the change didn't go through. When the contract already has a discount code that this one can't be combined with under the codes' **Combinations** settings in Shopify, the message names both, for example `SAVE10 cannot be combined with WELCOME15.`
* `idexists`: Shopify refused the code for this contract, and the message says why, for example `This discount doesn't apply to any of the products currently in this subscription.`
* No `errorKey`, `Discount is already applied`: a discount with this code is already on the contract.

The text after `UserGeneratedError:` is written for people: remove the prefix and show the rest to the customer or support agent. Handle an `errorKey` that isn't in this list the same way.

### Remove a discount

```bash theme={null}
curl -X PUT \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-remove-discount?contractId={contractId}&discountId=gid://shopify/SubscriptionManualDiscount/{discountId}" \
  -H "X-API-Key: YOUR_API_KEY"
```

`discountId` is the full `gid://` ID of the discount. Read it from the `discounts` of the apply response, or of [`GET /subscription-contracts/contract-external/{contractId}`](https://developers.appstle.com/subscription-admin-api/subscription-management/get-raw-shopify-graphql-contract-response).

A successful call returns `200` with the updated contract, and the discount is gone from `discounts.nodes[]`. An ID that isn't on the contract also returns `200` and changes nothing, so check `discounts` in the response to confirm the removal.

## Shipping

### Update shipping address

The contract goes in the query string and the address in a JSON body:

```bash theme={null}
curl -X PUT \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-shipping-address?contractId={contractId}" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "address1": "123 Main St",
    "city": "San Francisco",
    "provinceCode": "CA",
    "countryCode": "US",
    "zip": "94105",
    "methodType": "SHIPPING"
  }'
```

A successful call returns `200` with the updated contract. `methodType` is `SHIPPING` (the default), `LOCAL` for local delivery or `PICK_UP` for a pickup location. `PICK_UP` also needs `locationId`, the Shopify location ID of the pickup point. Without it, the call returns `400` with `UserGeneratedError:Choose a pickup location.` See the [reference](https://developers.appstle.com/subscription-admin-api/subscription-management/update-subscription-delivery-address-and-method.md) for every field.

## Past orders

### Get order history

```bash theme={null}
curl -X GET \
  "https://subscription-admin.appstle.com/api/external/v2/subscription-billing-attempts/past-orders?contractId={contractId}" \
  -H "X-API-Key: YOUR_API_KEY"
```

The last page also lists the contract's first order, with `id` set to `null`. `x-total-count` doesn't count it.

## Cancellation and pause records

### List retention activity

When a customer goes through the cancel or pause flow in the customer portal, Appstle records what happened: the reason they picked, the note they typed and whether they accepted a retention offer. `GET /api/external/v2/customer-retention-activities` returns these records for churn dashboards, CRM syncs and win-back automation. Cancelling or pausing a subscription with the Admin API, or with the Storefront API's cancel and pause endpoints from your own frontend, writes none.

> [!WARNING]
>
> Send `fromDay` and `toDay` as full ISO-8601 date-times with a `Z` suffix, such as `2026-11-01T00:00:00Z`. A date alone, such as `2026-11-01`, returns `400`.

```bash theme={null}
curl -G "https://subscription-admin.appstle.com/api/external/v2/customer-retention-activities" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "fromDay=2026-11-01T00:00:00Z" \
  --data-urlencode "toDay=2026-11-30T23:59:59Z" \
  --data-urlencode "eventSource=CANCELLATION" \
  --data-urlencode "size=50"
```

The response is a JSON array, newest record first (highest `id` first). The `x-total-count` header holds the number of matching records. `page` starts at `0` and `size` defaults to `20`. Don't send `sort`. The list is always newest first, and `sort=id,asc` or `sort=id,desc` returns `400` with `Internal Server Error` in the body.

> [!NOTE]
>
> The URLs in the `link` header don't work when you URL-encode the dates, as the example above does: the encoded `:` is encoded a second time, and calling those URLs returns `400`. Build the next page yourself: send the same parameters with `page` set to the next number, and stop when a page comes back with fewer than `size` records or when you have read `x-total-count` records.

```json theme={null}
[
  {
    "id": 4821,
    "status": "active",
    "contractId": 123456789012,
    "activityOn": "2026-11-04 04:03:20.0",
    "retentionAction": "0",
    "cancellationReason": "It is too expensive right now",
    "discountApplied": null,
    "additionalInfo": "{\"actionOption\":\"Too expensive\",\"cancellationFeedback\":\"It is too expensive right now\"}",
    "eventSource": "CANCELLATION",
    "shop": "your-store.myshopify.com",
    "customerName": "Jane Doe",
    "customerEmail": "jane.doe@example.com"
  }
]
```

| Field | What it holds |
| - | - |
| `retentionAction` | A numeric code, sent as a string. See the table below. |
| `eventSource` | `CANCELLATION` or `PAUSE`: the flow the customer was in, not what they did. A pause the customer accepts in the cancel flow is `CANCELLATION` with code `8`. |
| `status` | The status of the subscription right now (for example `active`, `paused` or `cancelled`), not of the record. |
| `cancellationReason` | The note the customer typed. `null` or empty when they wrote none. |
| `additionalInfo` | A JSON string, so parse it. `actionOption` is the reason the customer picked and `cancellationFeedback` is their note (`-` or `null` when they wrote none). Both are missing when the customer picked no reason. It can also hold `reasonId`, `offerTier` (`PRIMARY` for the first offer, `FALLBACK` for the fallback offer), `pauseDurationCycle` and `skipDurationCycle`, `discountCode` and `discountType` for code `1`, and `freeGiftVariantId` and `freeGiftTitle` for code `9`. Accept keys you don't recognize. |
| `discountApplied` | The title of the discount Appstle applied when the customer accepted a discount offer (code `1`), such as `cancel123456789012`. `null` for every other action. |
| `activityOn` | When the record was written, as `YYYY-MM-DD HH:MM:SS.S` in UTC. |

The `retentionAction` code says which offer the customer accepted:

| Code | Meaning |
| - | - |
| `0` | No offer accepted: the customer cancelled or paused without taking one, or the reason had no offer. |
| `1` | Discount. `discountApplied` holds the discount's title. |
| `2` | Swap |
| `3` | Gift: the customer changed the shipping address, the same change as `6`. |
| `4` | Skip |
| `5` | Change date |
| `6` | Change address |
| `7` | Update frequency |
| `8` | Pause |
| `9` | Free gift: a free one-time product was added to the next order. |

To see why customers leave, read `actionOption` in `additionalInfo`, because `cancellationReason` is only the free-text note. Accept codes you don't recognize, because new offer types get new codes.

You can filter the list with these query parameters. Each one is optional.

| Parameter | Matches |
| - | - |
| `contractId` | One subscription contract. |
| `eventSource` | `CANCELLATION` or `PAUSE`. |
| `retentionAction` | One code from the table, such as `2`. |
| `retentionReason` | The reason the customer picked (`actionOption`) or their note (`cancellationFeedback`), word for word. |
| `status` | The subscription's current status, such as `cancelled`. |
| `fromDay` | Records written at or after this date-time. Leave it out for no start limit. |
| `toDay` | Records written at or before this date-time. Leave it out for no end limit. |

This section lists every parameter. To try the call, use the playground in the [API reference](https://developers.appstle.com/subscription-admin-api/customer-retention/get-customer-retention-activities.md).

## Rate limits

The Admin API limits how many calls a store can make. Treat the numbers below as the most you should send: a call over one can get `429 Too Many Requests`, with a `Retry-After: 30` header and this body:

```json theme={null}
{"error":"Rate limit exceeded. Try again later."}
```

| Limit | Value |
| - | - |
| All calls from a store | 600 per minute, counting your Admin API calls, the store's storefront calls and the calls the Appstle app makes while the merchant uses it |
| Calls to one endpoint | 60 per minute. An endpoint is a path, whatever the method. Paths that differ only in a numeric ID, such as `/subscription-contracts/101` and `/subscription-contracts/102`, count as one endpoint, and so do calls that differ only in their query string, so reading contracts one at a time with `subscription-contract-details?subscriptionContractId=...` is limited to 60 a minute. |
| Calls to an endpoint that keeps failing | 10 per minute, once that endpoint has returned five or more error responses (status `400` or higher) in the same minute |
| Write calls in progress at once | 5 per store, storefront writes included. Every `PUT` counts, and so does a `POST` whose path contains `create-subscription-contract`, `replace-variants`, `split-existing-contract`, `merge-contract` or `update-custom-note-attributes`. A write sent while five are in progress can get `429` with the body `{"error":"Too many concurrent mutation requests. Please wait for existing requests to complete."}`. |

Calls made with a partner token count against the store the token acts for, together with the store's own API keys. A call with a missing, wrong or revoked key gets `401` before any limit is checked, so it never gets `429`. Retrying it won't help: fix the key.

When you get a `429`:

* **Wait before you retry.** Wait at least the `Retry-After` seconds, retry, and back off further if the `429` comes back. Retrying at once keeps you over the limit.
* **Don't retry a failing call in a loop.** After five error responses an endpoint allows only 10 calls a minute, so fix the request first.
* **Limit parallel writes.** Five writes in progress is the store's total, storefront writes included, so queue writes on your side and send a few at a time.

Storefront API calls have limits of their own: see [Rate limits](https://developers.appstle.com/subscription/build-your-own-frontend.md#rate-limits) in the storefront guide.

## Partner integrations

If you are building a platform that connects to Appstle on behalf of multiple merchants, use the [Partner Integration Framework](https://developers.appstle.com/subscription/partner-integration.md). It provides:

* A standard connection and merchant-approval flow
* One isolated, revocable API token per connected merchant
* External API access without requiring each merchant to purchase API access
* Automatic token revocation when a merchant disconnects

Your Partner Secret authenticates `/api/partner/...` connection calls through `X-Partner-Secret`. After an approved **Nonce Handshake**, use the issued merchant-scoped token as `X-API-Key` when calling `/api/external/v2/...`.

To get onboarded, email [support@appstle.com](mailto:support@appstle.com) with your company name, product description, base URL, and contact email. The [Partner integration guide](https://developers.appstle.com/subscription/partner-integration.md) lists the complete onboarding requirements and implementation steps.

## Further reading

> [card] [Webhooks](https://developers.appstle.com/subscription/webhooks.md)
>
> Receive real-time events when subscriptions change.

> [card] [Shopify Flow](https://developers.appstle.com/subscription/shopify-flow.md)
>
> No-code automation using Shopify's built-in workflow engine.

> [card] [Authentication](https://developers.appstle.com/subscription/authentication.md)
>
> Create, rotate, and revoke merchant API keys.

> [card] [Partner integration](https://developers.appstle.com/subscription/partner-integration.md)
>
> Connect your platform and receive scoped API tokens for merchants.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.