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

# API schema reference

> Every type, field, argument and enum of the Reval GraphQL API, with the same description introspection shows.

This page is the complete reference of the [Reval API](https://docs.appreval.com/en/developers/api.md) GraphQL schema: every query, action, object, input and enum, with the same description you see when you introspect the endpoint from GraphiQL, Insomnia or Postman. The guide explains how to authenticate, paginate and handle errors; this page answers "which fields does X have".

> [!NOTE]
>
> The schema is a **contract**: Reval adds fields and types, but never renames or removes published ones.

**How to read the types.** `String!` is required, `String` can be `null`. `[Plan!]!` is a required list of required items. Lists end in `Connection` and are paginated with `first` and `after` (see [Pagination](https://docs.appreval.com/en/developers/api.md#pagination)).

***

## Queries (`Query`)

### `shop`

Returns: [`Shop!`](#shop)

The store this API key belongs to.

### `subscription(id)`

Returns: [`Subscription`](#subscription)

One subscription by Reval id. Null when it does not exist in this store.

| Argument | Type | Description |
| - | - | - |
| `id` | `ID!` | — |

### `subscriptions(first, after, filter, sortKey, reverse)`

Returns: [`SubscriptionConnection!`](#subscriptionconnection)

Subscriptions of the store, newest first by default.

| Argument | Type | Description |
| - | - | - |
| `first` | `Int` | — |
| `after` | `String` | — |
| `filter` | [`SubscriptionFilter`](#subscriptionfilter) | — |
| `sortKey` | [`SubscriptionSortKey`](#subscriptionsortkey) | — |
| `reverse` | `Boolean` | Flip the sort direction (ascending for date keys). |

### `order(id)`

Returns: [`SubscriptionOrder`](#subscriptionorder)

One subscription order by Reval id.

| Argument | Type | Description |
| - | - | - |
| `id` | `ID!` | — |

### `orders(first, after, filter, reverse)`

Returns: [`SubscriptionOrderConnection!`](#subscriptionorderconnection)

Orders generated by subscriptions (one per charged cycle), newest first by default.

| Argument | Type | Description |
| - | - | - |
| `first` | `Int` | — |
| `after` | `String` | — |
| `filter` | [`OrderFilter`](#orderfilter) | — |
| `reverse` | `Boolean` | — |

### `customer(email)`

Returns: [`Customer`](#customer)

One customer by email (the identity Reval subscriptions are keyed by).

| Argument | Type | Description |
| - | - | - |
| `email` | `String!` | — |

### `customers(first, after, filter)`

Returns: [`CustomerConnection!`](#customerconnection)

Every customer with at least one subscription, by email.

| Argument | Type | Description |
| - | - | - |
| `first` | `Int` | — |
| `after` | `String` | — |
| `filter` | [`CustomerFilter`](#customerfilter) | — |

### `planGroup(id)`

Returns: [`PlanGroup`](#plangroup)

One plan (a set of terms many products can sell on) by id.

| Argument | Type | Description |
| - | - | - |
| `id` | `ID!` | — |

### `planGroups(first, after, filter)`

Returns: [`PlanGroupConnection!`](#plangroupconnection)

Plans of the store — what the admin calls «Planes».

| Argument | Type | Description |
| - | - | - |
| `first` | `Int` | — |
| `after` | `String` | — |
| `filter` | [`PlanGroupFilter`](#plangroupfilter) | — |

### `plan(id)`

Returns: [`Plan`](#plan)

One product offering (plan × variant) by id.

| Argument | Type | Description |
| - | - | - |
| `id` | `ID!` | — |

### `plans(first, after, filter)`

Returns: [`PlanConnection!`](#planconnection)

Product offerings: one row per variant attached to a plan.

| Argument | Type | Description |
| - | - | - |
| `first` | `Int` | — |
| `after` | `String` | — |
| `filter` | [`PlanFilter`](#planfilter) | — |

### `box(id)`

Returns: [`Box`](#box)

One box (bundle) by id.

| Argument | Type | Description |
| - | - | - |
| `id` | `ID!` | — |

### `boxes(first, after, filter)`

Returns: [`BoxConnection!`](#boxconnection)

Boxes of the store — what the admin calls «Cajas».

| Argument | Type | Description |
| - | - | - |
| `first` | `Int` | — |
| `after` | `String` | — |
| `filter` | [`BoxFilter`](#boxfilter) | — |

***

## Actions (`Mutation`)

### `subscriptionPause(id, overrideMinCycles)`

Returns: [`SubscriptionPayload!`](#subscriptionpayload)

Pause an ACTIVE subscription: Mercado Pago stops charging until it is resumed. Applies the plan's minimum commitment like the portal does; `overrideMinCycles: true` acts as the merchant and skips that gate.

| Argument | Type | Description |
| - | - | - |
| `id` | `ID!` | — |
| `overrideMinCycles` | `Boolean` | — |

### `subscriptionResume(id)`

Returns: [`SubscriptionPayload!`](#subscriptionpayload)

Resume a PAUSED subscription; Mercado Pago picks up the schedule and sets the next charge date.

| Argument | Type | Description |
| - | - | - |
| `id` | `ID!` | — |

### `subscriptionCancel(id, reason, note, overrideMinCycles)`

Returns: [`SubscriptionPayload!`](#subscriptionpayload)

Cancel a subscription with a reason (the same list the portal offers) and an optional free-text note. Applies the minimum commitment like the portal unless `overrideMinCycles: true`.

| Argument | Type | Description |
| - | - | - |
| `id` | `ID!` | — |
| `reason` | [`CancelReason!`](#cancelreason) | — |
| `note` | `String` | — |
| `overrideMinCycles` | `Boolean` | — |

### `subscriptionSkipNextCycle(id)`

Returns: [`SubscriptionPayload!`](#subscriptionpayload)

Skip the next cycle of an ACTIVE subscription: that cycle is neither charged nor shipped; the mandate resumes on its own on the following one. Honours the store's skip settings and the minimum commitment.

| Argument | Type | Description |
| - | - | - |
| `id` | `ID!` | — |

### `subscriptionSetItems(id, items)`

Returns: [`SubscriptionPayload!`](#subscriptionpayload)

Replace the product lines with the given set (one line per plan; the same plan twice sums the quantities). Every plan must be active in this store and bill on the subscription's cadence — Mercado Pago mandates keep their frequency. The total is recomputed from plan prices, shipping is re-quoted and Mercado Pago is updated for the next cycle. Box subscriptions are edited by the subscriber in the portal, not here.

| Argument | Type | Description |
| - | - | - |
| `id` | `ID!` | — |
| `items` | [`[SubscriptionItemInput!]!`](#subscriptioniteminput) | — |

### `subscriptionUpdateShippingAddress(id, address)`

Returns: [`SubscriptionPayload!`](#subscriptionpayload)

Replace the shipping address used for the next orders. address1, city and zip are required; the country stays unless given. The shipping rate is not re-quoted.

| Argument | Type | Description |
| - | - | - |
| `id` | `ID!` | — |
| `address` | [`AddressInput!`](#addressinput) | — |

### `subscriptionPortalLink(id)`

Returns: [`PortalLinkPayload!`](#portallinkpayload)

A signed, time-limited link that opens this subscriber's self-service portal on the store's primary domain — what the admin's «Copiar Portal Link» does. Treat it as a credential: it logs the subscriber in.

| Argument | Type | Description |
| - | - | - |
| `id` | `ID!` | — |

### `checkoutLinkCreate(lines, customer, externalRef)`

Returns: [`CheckoutLinkPayload!`](#checkoutlinkpayload)

Create a checkout link. Every line names a `planId` — a subscription link that opens Reval's checkout: several products, several cadences, one card entry, one subscription per cadence — or every line a bare `variantId` — a one-time link, a Shopify cart permalink. Customer prefill (editable by the shopper; never in the URL) and `externalRef` (stamped on the subscriptions the link creates, echoed in the API and the subscription webhooks as `external_ref`) need a subscription link. A link carrying customer data expires 30 days after creation and is single-use; without it the URL is permanent. Send an `Idempotency-Key` so a retry returns the same link.

| Argument | Type | Description |
| - | - | - |
| `lines` | `[CheckoutLinkLineInput!]!` | `{ planId, variantId, quantity }` — `planId` for a subscription line (see `plans`), bare `variantId` only for one-time. |
| `customer` | `CheckoutLinkCustomerInput` | Optional prefill: `email`, `firstName`, `lastName`, `phone`, `company`, `taxId`, `address { address1, address2, streetNumber, city, province, zip, countryCode }`. All editable by the shopper; the store's field rules win. |
| `externalRef` | `String` | Your own reference (ticket/conversation id). Comes back on `Subscription.externalRef` and in the webhooks. |

***

## Objects

### UserError

| Field | Type | Description |
| - | - | - |
| `code` | [`UserErrorCode!`](#usererrorcode) | — |
| `message` | `String!` | Human-readable; for logs, not for branching. |
| `field` | `String` | The argument at fault, when one is. |

### SubscriptionPayload

| Field | Type | Description |
| - | - | - |
| `subscription` | [`Subscription`](#subscription) | The subscription after the change. Null when userErrors is not empty. |
| `userErrors` | [`[UserError!]!`](#usererror) | — |

### PortalLinkPayload

| Field | Type | Description |
| - | - | - |
| `url` | `String` | — |
| `expiresAt` | `DateTime` | — |
| `userErrors` | [`[UserError!]!`](#usererror) | — |

### CheckoutLinkPayload

| Field | Type | Description |
| - | - | - |
| `url` | `String` | Ready to share. Null when userErrors is not empty. |
| `expiresAt` | `DateTime` | Null = the link is permanent (it carries no customer data). |
| `userErrors` | [`[UserError!]!`](#usererror) | — |

### Shop

| Field | Type | Description |
| - | - | - |
| `myshopifyDomain` | `String!` | The store's permanent myshopify.com domain. |
| `locale` | `String!` | The language the store runs Reval in: es, es-419 or pt. |

### Subscription

| Field | Type | Description |
| - | - | - |
| `id` | `ID!` | — |
| `status` | [`SubscriptionStatus!`](#subscriptionstatus) | — |
| `customer` | [`Customer!`](#customer) | — |
| `customerEmail` | `String!` | — |
| `shopifyCustomerId` | `ID` | Shopify Customer GID, when the shopper matched a Shopify customer. |
| `mercadoPagoPreapprovalId` | `String` | Mercado Pago preapproval (mandate) id, for reconciliation against your MP account. |
| `amount` | `Money!` | The recurring total charged each cycle: products + shipping + tax when applicable. |
| `currency` | `String!` | — |
| `nextPaymentDate` | `DateTime` | Next scheduled charge. Null while pending, cancelled or completed. |
| `plan` | [`Plan`](#plan) | The plan this subscription is billed on (its cadence and pricing). |
| `planGroup` | [`PlanGroup`](#plangroup) | The plan's terms (the admin «Plan»). |
| `frequency` | `Int` | Cadence: every N `frequencyType`. Null on legacy rows without a plan. |
| `frequencyType` | [`FrequencyType`](#frequencytype) | — |
| `items` | [`[SubscriptionItem!]!`](#subscriptionitem) | The products delivered each cycle. |
| `shopifyVariantId` | `ID!` | Primary product's variant (the first line), kept for single-product reads. |
| `quantity` | `Int!` | Primary product's quantity. |
| `box` | [`Box`](#box) | When this subscription is a box, the box it was composed from. |
| `boxSizeId` | `ID` | — |
| `shippingAddress` | [`Address`](#address) | — |
| `shipping` | [`ShippingLine`](#shippingline) | The shipping rate chosen at signup, locked for every cycle. Null = no rate (\$0). |
| `tax` | [`TaxLine`](#taxline) | Tax locked at signup. Null = no tax. |
| `taxId` | `String` | Fiscal document (CUIT/CPF/RUT…) typed at checkout, when the store collects it. |
| `externalRef` | `String` | The merchant's own reference from the checkout link that created this subscription (`checkoutLinkCreate`). |
| `paymentMethod` | [`PaymentCard`](#paymentcard) | Masked card behind the mandate. Never the number. |
| `lastPaymentFailedAt` | `DateTime` | Dunning: set when Mercado Pago rejected the last cycle, cleared by the next approved one. |
| `lastPaymentFailReason` | `String` | — |
| `lastPaymentPendingAt` | `DateTime` | A cycle charge Mercado Pago is still reviewing. |
| `cyclesCompletedAt` | `DateTime` | Set when the plan's maximum cycles were reached; the subscription stays ACTIVE but no longer charges. |
| `skipResumeAt` | `DateTime` | When a PAUSED subscription is actually a skipped cycle: the date it resumes on its own. |
| `reactivatedFromId` | `ID` | Id of the cancelled subscription this one was reactivated from. |
| `streakCount` | `Int!` | Consecutive on-time cycles (Sorpresas streak). |
| `cycleCount` | `Int!` | Charged cycles so far. |
| `orders(first, after, reverse)` | [`SubscriptionOrderConnection!`](#subscriptionorderconnection) | Orders generated by this subscription, newest first. |
| `statusHistory` | [`[StatusChange!]!`](#statuschange) | Status changes, newest first (last 100). |
| `priceHistory` | [`[PriceChange!]!`](#pricechange) | Amount changes, newest first (last 100). |
| `createdAt` | `DateTime!` | — |
| `updatedAt` | `DateTime!` | — |

### SubscriptionItem

| Field | Type | Description |
| - | - | - |
| `id` | `ID!` | — |
| `shopifyVariantId` | `ID!` | Shopify ProductVariant GID. |
| `quantity` | `Int!` | — |
| `unitAmount` | `Money!` | Catalog unit price at the plan's terms (display/analytics; the charged total is Subscription.amount). |
| `role` | [`SubscriptionItemRole!`](#subscriptionitemrole) | — |
| `plan` | [`Plan`](#plan) | — |
| `createdAt` | `DateTime!` | — |

### Address

| Field | Type | Description |
| - | - | - |
| `firstName` | `String` | — |
| `lastName` | `String` | — |
| `company` | `String` | — |
| `address1` | `String` | — |
| `address2` | `String` | — |
| `city` | `String` | — |
| `province` | `String` | — |
| `zip` | `String` | — |
| `countryCode` | `String` | ISO 3166-1 alpha-2. |
| `phone` | `String` | — |

### ShippingLine

| Field | Type | Description |
| - | - | - |
| `title` | `String` | — |
| `amount` | `Money!` | — |

### TaxLine

| Field | Type | Description |
| - | - | - |
| `title` | `String` | — |
| `amount` | `Money!` | — |
| `rate` | `String` | Effective rate as a fraction, e.g. "0.21000". |
| `included` | `Boolean!` | True when the amount is inside Subscription.amount rather than added on top. |

### PaymentCard

| Field | Type | Description |
| - | - | - |
| `brand` | `String` | Mercado Pago payment\_method\_id: visa, master, amex… |
| `last4` | `String` | — |
| `expMonth` | `Int` | — |
| `expYear` | `Int` | — |

### StatusChange

| Field | Type | Description |
| - | - | - |
| `id` | `ID!` | — |
| `fromStatus` | [`SubscriptionStatus!`](#subscriptionstatus) | — |
| `toStatus` | [`SubscriptionStatus!`](#subscriptionstatus) | — |
| `source` | [`StatusChangeSource!`](#statuschangesource) | — |
| `reason` | `String` | Cancellation reason, when one was given. |
| `changedAt` | `DateTime!` | — |

### PriceChange

| Field | Type | Description |
| - | - | - |
| `id` | `ID!` | — |
| `oldAmount` | `Money!` | — |
| `newAmount` | `Money!` | — |
| `source` | [`PriceChangeSource!`](#pricechangesource) | — |
| `changedAt` | `DateTime!` | — |

### SubscriptionEdge

| Field | Type | Description |
| - | - | - |
| `cursor` | `String!` | — |
| `node` | [`Subscription!`](#subscription) | — |

### SubscriptionConnection

| Field | Type | Description |
| - | - | - |
| `edges` | [`[SubscriptionEdge!]!`](#subscriptionedge) | — |
| `nodes` | [`[Subscription!]!`](#subscription) | — |
| `pageInfo` | [`PageInfo!`](#pageinfo) | — |
| `totalCount` | `Int!` | Rows matching the filter, regardless of the page. |

### SubscriptionOrder

| Field | Type | Description |
| - | - | - |
| `id` | `ID!` | — |
| `subscription` | [`Subscription!`](#subscription) | — |
| `shopifyOrderId` | `ID` | Shopify Order GID. Null while the order is on hold (see holdReason) or failed to create. |
| `shopifyOrderName` | `String` | Shopify order name, e.g. "#1234". |
| `mercadoPagoPaymentId` | `String` | Mercado Pago payment id of the charge that produced this order. |
| `type` | [`OrderType!`](#ordertype) | — |
| `amount` | `Money` | Amount charged for this cycle. |
| `currency` | `String` | — |
| `quantity` | `Int` | Units shipped. |
| `cycleNumber` | `Int!` | 1-based cycle number within the subscription. |
| `holdReason` | `String` | Why the Shopify order has not been created: oos\_retry, oos\_skipped, awaiting\_checkout\_upsell, awaiting\_merge… |
| `fulfillmentStatus` | `String` | Shopify displayFulfillmentStatus, as last seen. |
| `createdAt` | `DateTime!` | — |

### SubscriptionOrderEdge

| Field | Type | Description |
| - | - | - |
| `cursor` | `String!` | — |
| `node` | [`SubscriptionOrder!`](#subscriptionorder) | — |

### SubscriptionOrderConnection

| Field | Type | Description |
| - | - | - |
| `edges` | [`[SubscriptionOrderEdge!]!`](#subscriptionorderedge) | — |
| `nodes` | [`[SubscriptionOrder!]!`](#subscriptionorder) | — |
| `pageInfo` | [`PageInfo!`](#pageinfo) | — |
| `totalCount` | `Int!` | — |

### Customer

A subscriber. Reval identifies customers by email; the Shopify customer is attached when it matched.

| Field | Type | Description |
| - | - | - |
| `email` | `String!` | — |
| `shopifyCustomerId` | `ID` | — |
| `firstName` | `String` | From the most recent subscription's shipping address. |
| `lastName` | `String` | — |
| `phone` | `String` | — |
| `subscriptionCount` | `Int!` | — |
| `activeSubscriptionCount` | `Int!` | — |
| `subscriptions(first, after, filter, sortKey, reverse)` | [`SubscriptionConnection!`](#subscriptionconnection) | — |
| `orders(first, after, reverse)` | [`SubscriptionOrderConnection!`](#subscriptionorderconnection) | — |
| `createdAt` | `DateTime!` | When their first subscription was created. |

### CustomerEdge

| Field | Type | Description |
| - | - | - |
| `cursor` | `String!` | — |
| `node` | [`Customer!`](#customer) | — |

### CustomerConnection

| Field | Type | Description |
| - | - | - |
| `edges` | [`[CustomerEdge!]!`](#customeredge) | — |
| `nodes` | [`[Customer!]!`](#customer) | — |
| `pageInfo` | [`PageInfo!`](#pageinfo) | — |
| `totalCount` | `Int!` | — |

### PlanGroup

A plan as the merchant defines it: cadence and pricing that many products sell on (the admin «Plan»).

| Field | Type | Description |
| - | - | - |
| `id` | `ID!` | — |
| `type` | [`PlanGroupType!`](#plangrouptype) | — |
| `title` | `String!` | — |
| `displayName` | `String` | Optional storefront label shown instead of the cadence. |
| `frequency` | `Int!` | Every `frequency` `frequencyType`, e.g. 1 MONTHS. |
| `frequencyType` | [`FrequencyType!`](#frequencytype) | — |
| `priceType` | [`PlanPriceType!`](#planpricetype) | — |
| `discountPercent` | `Int` | — |
| `amount` | `Money` | FIXED: the price per cycle. PERCENT: null. |
| `firstOrderDiscountPercent` | `Int!` | Extra percentage off the first cycle only. 0 = none. |
| `minCycles` | `Int` | Cycles the customer must pay before they can pause or cancel on their own. |
| `maxCycles` | `Int` | The subscription completes after this many charged cycles. |
| `currency` | `String!` | — |
| `status` | [`PlanStatus!`](#planstatus) | — |
| `plans` | [`[Plan!]!`](#plan) | The product offerings attached to this plan. |
| `createdAt` | `DateTime!` | — |
| `updatedAt` | `DateTime!` | — |

### PlanGroupEdge

| Field | Type | Description |
| - | - | - |
| `cursor` | `String!` | — |
| `node` | [`PlanGroup!`](#plangroup) | — |

### PlanGroupConnection

| Field | Type | Description |
| - | - | - |
| `edges` | [`[PlanGroupEdge!]!`](#plangroupedge) | — |
| `nodes` | [`[PlanGroup!]!`](#plangroup) | — |
| `pageInfo` | [`PageInfo!`](#pageinfo) | — |
| `totalCount` | `Int!` | — |

### Plan

One product variant sold on one plan: the row a subscription is billed on.

| Field | Type | Description |
| - | - | - |
| `id` | `ID!` | — |
| `name` | `String` | — |
| `displayName` | `String` | — |
| `shopifyVariantId` | `ID!` | Shopify ProductVariant GID. |
| `frequency` | `Int!` | — |
| `frequencyType` | [`FrequencyType!`](#frequencytype) | — |
| `priceType` | [`PlanPriceType!`](#planpricetype) | — |
| `discountPercent` | `Int` | — |
| `amount` | `Money!` | FIXED: the price. PERCENT: the last computed price snapshot. |
| `currency` | `String!` | — |
| `status` | [`PlanStatus!`](#planstatus) | — |
| `firstOrderDiscountPercent` | `Int!` | — |
| `minCycles` | `Int` | — |
| `maxCycles` | `Int` | — |
| `group` | [`PlanGroup`](#plangroup) | — |
| `createdAt` | `DateTime!` | — |
| `updatedAt` | `DateTime!` | — |

### PlanEdge

| Field | Type | Description |
| - | - | - |
| `cursor` | `String!` | — |
| `node` | [`Plan!`](#plan) | — |

### PlanConnection

| Field | Type | Description |
| - | - | - |
| `edges` | [`[PlanEdge!]!`](#planedge) | — |
| `nodes` | [`[Plan!]!`](#plan) | — |
| `pageInfo` | [`PageInfo!`](#pageinfo) | — |
| `totalCount` | `Int!` | — |

### Box

A bundle the shopper composes (the admin «Caja»).

| Field | Type | Description |
| - | - | - |
| `id` | `ID!` | — |
| `title` | `String!` | — |
| `handle` | `String!` | Slug of the box's storefront page. |
| `description` | `String` | — |
| `imageUrl` | `String` | — |
| `type` | [`BoxType!`](#boxtype) | — |
| `shopifyProductId` | `ID` | The Shopify product that represents the box. |
| `shopifyVariantId` | `ID` | The box product's single variant. |
| `status` | [`PlanStatus!`](#planstatus) | — |
| `sizeMode` | [`BoxSizeMode!`](#boxsizemode) | — |
| `minItems` | `Int` | — |
| `maxItems` | `Int` | — |
| `planGroups` | [`[PlanGroup!]!`](#plangroup) | The plans (cadences) this box sells on, default first. |
| `sizes` | [`[BoxSize!]!`](#boxsize) | — |
| `options` | [`[BoxOption!]!`](#boxoption) | — |
| `tiers` | [`[BoxTier!]!`](#boxtier) | — |
| `createdAt` | `DateTime!` | — |
| `updatedAt` | `DateTime!` | — |

### BoxSize

| Field | Type | Description |
| - | - | - |
| `id` | `ID!` | — |
| `itemCount` | `Int!` | — |
| `shopifyVariantId` | `ID` | CLASSIC: the variant that carries the price. |
| `amount` | `Money` | CLASSIC: the price for this size. |
| `discountType` | `String` | DYNAMIC: percent \| fixed. |
| `discountValue` | `Money` | — |

### BoxOption

| Field | Type | Description |
| - | - | - |
| `id` | `ID!` | — |
| `shopifyVariantId` | `ID!` | — |
| `kind` | [`BoxOptionKind!`](#boxoptionkind) | — |

### BoxTier

| Field | Type | Description |
| - | - | - |
| `id` | `ID!` | — |
| `basis` | `String!` | quantity \| amount. |
| `threshold` | `Money!` | — |
| `discountType` | `String!` | percent \| fixed. |
| `value` | `Money!` | — |

### BoxEdge

| Field | Type | Description |
| - | - | - |
| `cursor` | `String!` | — |
| `node` | [`Box!`](#box) | — |

### BoxConnection

| Field | Type | Description |
| - | - | - |
| `edges` | [`[BoxEdge!]!`](#boxedge) | — |
| `nodes` | [`[Box!]!`](#box) | — |
| `pageInfo` | [`PageInfo!`](#pageinfo) | — |
| `totalCount` | `Int!` | — |

### PageInfo

| Field | Type | Description |
| - | - | - |
| `hasNextPage` | `Boolean!` | — |
| `endCursor` | `String` | Pass as `after` to fetch the next page. Null on the last page. |

***

## Inputs

### SubscriptionItemInput

| Field | Type | Description |
| - | - | - |
| `planId` | `ID!` | The Plan (product offering) id — see `plans`. |
| `quantity` | `Int!` | — |

### AddressInput

| Field | Type | Description |
| - | - | - |
| `firstName` | `String` | — |
| `lastName` | `String` | — |
| `company` | `String` | — |
| `address1` | `String!` | — |
| `address2` | `String` | — |
| `city` | `String!` | — |
| `province` | `String` | — |
| `zip` | `String!` | — |
| `countryCode` | `String` | ISO 3166-1 alpha-2. Omitted = keep the subscription's current country. |
| `phone` | `String` | — |
| `streetNumber` | `String` | Brazil only: the street number, kept apart from address1 in the editors. |

### SubscriptionFilter

| Field | Type | Description |
| - | - | - |
| `status` | [`[SubscriptionStatus!]`](#subscriptionstatus) | One or more statuses; omitted = every status. |
| `customerEmail` | `String` | Exact email match (case-insensitive). |
| `shopifyCustomerId` | `ID` | — |
| `shopifyVariantId` | `ID` | Subscriptions that include this variant, as the primary product or any line. |
| `planGroupId` | `ID` | — |
| `boxId` | `ID` | — |
| `createdAfter` | `DateTime` | — |
| `createdBefore` | `DateTime` | — |
| `updatedAfter` | `DateTime` | — |
| `nextPaymentAfter` | `DateTime` | — |
| `nextPaymentBefore` | `DateTime` | — |

### OrderFilter

| Field | Type | Description |
| - | - | - |
| `subscriptionId` | `ID` | — |
| `customerEmail` | `String` | — |
| `type` | [`OrderType`](#ordertype) | — |
| `shopifyOrderId` | `ID` | — |
| `createdAfter` | `DateTime` | — |
| `createdBefore` | `DateTime` | — |

### CustomerFilter

| Field | Type | Description |
| - | - | - |
| `emailContains` | `String` | Substring match on the email (case-insensitive). |
| `shopifyCustomerId` | `ID` | — |

### PlanGroupFilter

| Field | Type | Description |
| - | - | - |
| `status` | [`PlanStatus`](#planstatus) | — |
| `type` | [`PlanGroupType`](#plangrouptype) | — |

### PlanFilter

| Field | Type | Description |
| - | - | - |
| `status` | [`PlanStatus`](#planstatus) | — |
| `shopifyVariantId` | `ID` | — |
| `planGroupId` | `ID` | — |

### BoxFilter

| Field | Type | Description |
| - | - | - |
| `status` | [`PlanStatus`](#planstatus) | — |
| `type` | [`BoxType`](#boxtype) | — |

***

## Enums

### CancelReason

The cancellation reasons the portal offers; stored with the subscription and shown in the churn analysis.

| Value | Description |
| - | - |
| `TOO_EXPENSIVE` | — |
| `PRODUCT_PILED_UP` | — |
| `WANT_ANOTHER_PRODUCT` | — |
| `DELIVERY_PROBLEMS` | — |
| `NO_LONGER_NEEDED` | — |
| `OTHER` | — |

### UserErrorCode

| Value | Description |
| - | - |
| `NOT_FOUND` | No subscription with that id in this store. |
| `INVALID_STATE` | The subscription's status does not allow the action (e.g. pausing a PAUSED one). |
| `MIN_CYCLES` | The plan's minimum commitment is not met; see overrideMinCycles. |
| `SKIP_NOT_ALLOWED` | The store's skip rules refuse it (skips disabled, already skipped, no next date…). |
| `PLAN_UNAVAILABLE` | A plan does not exist in this store or is archived. |
| `FREQUENCY_MISMATCH` | A plan bills on another cadence than the subscription. |
| `BELOW_MINIMUM` | The new total is below Mercado Pago's minimum charge for the currency. |
| `INVALID_INPUT` | Malformed input: empty items, bad quantity, incomplete address… |
| `MERCADO_PAGO_ERROR` | Mercado Pago refused the change; nothing was applied. |
| `REJECTED` | Any other rule the admin applies too; the message says which. |

### SubscriptionStatus

| Value | Description |
| - | - |
| `PENDING` | Created at checkout, Mercado Pago has not confirmed the mandate yet. |
| `ACTIVE` | Authorized and billing on schedule. |
| `PAUSED` | Charges stopped until resumed (also how a skipped cycle is represented). |
| `CANCELLED` | — |
| `COMPLETED` | Legacy: no longer written. A subscription that reached its last cycle stays ACTIVE with cyclesCompletedAt set. |

### SubscriptionSortKey

| Value | Description |
| - | - |
| `CREATED_AT` | — |
| `UPDATED_AT` | — |
| `NEXT_PAYMENT_DATE` | — |

### SubscriptionItemRole

| Value | Description |
| - | - |
| `PLAIN` | A regular product line. |
| `BOX_PARENT` | The priced line of a classic box; its contents are BOX\_CHILD lines at 0.00. |
| `BOX_CHILD` | — |

### StatusChangeSource

| Value | Description |
| - | - |
| `MERCHANT` | — |
| `CUSTOMER` | — |
| `MP` | Mercado Pago (e.g. the mandate was cancelled after repeated failures). |
| `SYSTEM` | — |
| `API` | A mutation of this API (SUB-168). |
| `OTHER` | — |

### PriceChangeSource

| Value | Description |
| - | - |
| `MERCHANT` | — |
| `CUSTOMER` | — |
| `API` | A mutation of this API (SUB-168). |

### OrderType

| Value | Description |
| - | - |
| `FIRST` | The first cycle, charged at checkout. |
| `RENEWAL` | — |

### FrequencyType

| Value | Description |
| - | - |
| `DAYS` | — |
| `WEEKS` | — |
| `MONTHS` | — |

### PlanPriceType

| Value | Description |
| - | - |
| `FIXED` | A fixed amount per cycle. |
| `PERCENT` | A percentage off the variant's live Shopify price. |

### PlanStatus

| Value | Description |
| - | - |
| `ACTIVE` | — |
| `ARCHIVED` | — |

### PlanGroupType

| Value | Description |
| - | - |
| `STANDARD` | Subscribe & save: terms applied to each attached product variant. |
| `DYNAMIC_BOX` | A dynamic box's own plan: cadence + discount, no per-variant fan-out. |

### BoxType

| Value | Description |
| - | - |
| `CLASSIC` | Fixed-price sizes; contents are free lines under a priced parent. |
| `DYNAMIC` | Priced from the chosen products' live prices, with size/tier discounts. |

### BoxSizeMode

| Value | Description |
| - | - |
| `FIXED` | — |
| `SIZES` | — |
| `RANGE` | — |

### BoxOptionKind

| Value | Description |
| - | - |
| `ELIGIBLE` | A product the shopper can put in the recurring box. |
| `ONE_TIME_UPSELL` | A one-time add-on offered before confirming. |

***

## Scalars

| Type | Description |
| - | - |
| `DateTime` | ISO-8601 date-time in UTC, e.g. `"2026-11-02T13:00:00.000Z"`. |
| `Money` | Decimal amount as a string with two decimals, e.g. `"18500.00"`. The currency is in the `currency` field of the same object. |
| `ID` | Opaque Reval identifier. Always use the one the API returned. |
| `Int` | Integer. |
| `String` | Text. |
| `Boolean` | `true` or `false`. |


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