> ## 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.

# Referência do esquema da API

> Todos os tipos, campos, argumentos e enums da API GraphQL da Reval, com a mesma descrição que a introspecção mostra.

Esta página é a referência completa do esquema GraphQL da [API da Reval](https://docs.appreval.com/pt/desenvolvedores/api.md): cada consulta, ação, objeto, input e enum, com a mesma descrição que você vê ao introspectar o endpoint pelo GraphiQL, Insomnia ou Postman. O guia explica como autenticar, paginar e tratar erros; esta página responde «quais campos X tem».

> [!NOTE]
>
> O esquema é um **contrato**: a Reval adiciona campos e tipos, mas não renomeia nem remove os publicados. As descrições estão em inglês porque são as mesmas que a introspecção devolve.

**Como ler os tipos.** `String!` é obrigatório, `String` pode ser `null`. `[Plan!]!` é uma lista obrigatória de itens obrigatórios. As listagens terminam em `Connection` e são paginadas com `first` e `after` (veja [Paginação](https://docs.appreval.com/pt/desenvolvedores/api.md#paginação)).

***

## Consultas (`Query`)

### `shop`

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

The store this API key belongs to.

### `subscription(id)`

Devolve: [`Subscription`](#subscription)

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

| Argumento | Tipo | Descrição |
| - | - | - |
| `id` | `ID!` | — |

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

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

Subscriptions of the store, newest first by default.

| Argumento | Tipo | Descrição |
| - | - | - |
| `first` | `Int` | — |
| `after` | `String` | — |
| `filter` | [`SubscriptionFilter`](#subscriptionfilter) | — |
| `sortKey` | [`SubscriptionSortKey`](#subscriptionsortkey) | — |
| `reverse` | `Boolean` | Flip the sort direction (ascending for date keys). |

### `order(id)`

Devolve: [`SubscriptionOrder`](#subscriptionorder)

One subscription order by Reval id.

| Argumento | Tipo | Descrição |
| - | - | - |
| `id` | `ID!` | — |

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

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

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

| Argumento | Tipo | Descrição |
| - | - | - |
| `first` | `Int` | — |
| `after` | `String` | — |
| `filter` | [`OrderFilter`](#orderfilter) | — |
| `reverse` | `Boolean` | — |

### `customer(email)`

Devolve: [`Customer`](#customer)

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

| Argumento | Tipo | Descrição |
| - | - | - |
| `email` | `String!` | — |

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

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

Every customer with at least one subscription, by email.

| Argumento | Tipo | Descrição |
| - | - | - |
| `first` | `Int` | — |
| `after` | `String` | — |
| `filter` | [`CustomerFilter`](#customerfilter) | — |

### `planGroup(id)`

Devolve: [`PlanGroup`](#plangroup)

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

| Argumento | Tipo | Descrição |
| - | - | - |
| `id` | `ID!` | — |

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

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

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

| Argumento | Tipo | Descrição |
| - | - | - |
| `first` | `Int` | — |
| `after` | `String` | — |
| `filter` | [`PlanGroupFilter`](#plangroupfilter) | — |

### `plan(id)`

Devolve: [`Plan`](#plan)

One product offering (plan × variant) by id.

| Argumento | Tipo | Descrição |
| - | - | - |
| `id` | `ID!` | — |

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

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

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

| Argumento | Tipo | Descrição |
| - | - | - |
| `first` | `Int` | — |
| `after` | `String` | — |
| `filter` | [`PlanFilter`](#planfilter) | — |

### `box(id)`

Devolve: [`Box`](#box)

One box (bundle) by id.

| Argumento | Tipo | Descrição |
| - | - | - |
| `id` | `ID!` | — |

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

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

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

| Argumento | Tipo | Descrição |
| - | - | - |
| `first` | `Int` | — |
| `after` | `String` | — |
| `filter` | [`BoxFilter`](#boxfilter) | — |

***

## Ações (`Mutation`)

### `subscriptionPause(id, overrideMinCycles)`

Devolve: [`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.

| Argumento | Tipo | Descrição |
| - | - | - |
| `id` | `ID!` | — |
| `overrideMinCycles` | `Boolean` | — |

### `subscriptionResume(id)`

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

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

| Argumento | Tipo | Descrição |
| - | - | - |
| `id` | `ID!` | — |

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

Devolve: [`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`.

| Argumento | Tipo | Descrição |
| - | - | - |
| `id` | `ID!` | — |
| `reason` | [`CancelReason!`](#cancelreason) | — |
| `note` | `String` | — |
| `overrideMinCycles` | `Boolean` | — |

### `subscriptionSkipNextCycle(id)`

Devolve: [`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.

| Argumento | Tipo | Descrição |
| - | - | - |
| `id` | `ID!` | — |

### `subscriptionSetItems(id, items)`

Devolve: [`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.

| Argumento | Tipo | Descrição |
| - | - | - |
| `id` | `ID!` | — |
| `items` | [`[SubscriptionItemInput!]!`](#subscriptioniteminput) | — |

### `subscriptionUpdateShippingAddress(id, address)`

Devolve: [`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.

| Argumento | Tipo | Descrição |
| - | - | - |
| `id` | `ID!` | — |
| `address` | [`AddressInput!`](#addressinput) | — |

### `subscriptionPortalLink(id)`

Devolve: [`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.

| Argumento | Tipo | Descrição |
| - | - | - |
| `id` | `ID!` | — |

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

Devolve: [`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.

| Argumento | Tipo | Descrição |
| - | - | - |
| `lines` | `[CheckoutLinkLineInput!]!` | `{ planId, variantId, quantity }` — `planId` para uma linha de assinatura (veja `plans`), `variantId` só para compra única. |
| `customer` | `CheckoutLinkCustomerInput` | Prefill opcional: `email`, `firstName`, `lastName`, `phone`, `company`, `taxId`, `address { address1, address2, streetNumber, city, province, zip, countryCode }`. Tudo editável pelo cliente; as regras de campos da loja mandam. |
| `externalRef` | `String` | Sua própria referência (id de ticket/conversa). Volta em `Subscription.externalRef` e nos webhooks. |

***

## Objetos

### UserError

| Campo | Tipo | Descrição |
| - | - | - |
| `code` | [`UserErrorCode!`](#usererrorcode) | — |
| `message` | `String!` | Human-readable; for logs, not for branching. |
| `field` | `String` | The argument at fault, when one is. |

### SubscriptionPayload

| Campo | Tipo | Descrição |
| - | - | - |
| `subscription` | [`Subscription`](#subscription) | The subscription after the change. Null when userErrors is not empty. |
| `userErrors` | [`[UserError!]!`](#usererror) | — |

### PortalLinkPayload

| Campo | Tipo | Descrição |
| - | - | - |
| `url` | `String` | — |
| `expiresAt` | `DateTime` | — |
| `userErrors` | [`[UserError!]!`](#usererror) | — |

### CheckoutLinkPayload

| Campo | Tipo | Descrição |
| - | - | - |
| `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

| Campo | Tipo | Descrição |
| - | - | - |
| `myshopifyDomain` | `String!` | The store's permanent myshopify.com domain. |
| `locale` | `String!` | The language the store runs Reval in: es, es-419 or pt. |

### Subscription

| Campo | Tipo | Descrição |
| - | - | - |
| `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

| Campo | Tipo | Descrição |
| - | - | - |
| `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

| Campo | Tipo | Descrição |
| - | - | - |
| `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

| Campo | Tipo | Descrição |
| - | - | - |
| `title` | `String` | — |
| `amount` | `Money!` | — |

### TaxLine

| Campo | Tipo | Descrição |
| - | - | - |
| `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

| Campo | Tipo | Descrição |
| - | - | - |
| `brand` | `String` | Mercado Pago payment\_method\_id: visa, master, amex… |
| `last4` | `String` | — |
| `expMonth` | `Int` | — |
| `expYear` | `Int` | — |

### StatusChange

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | `ID!` | — |
| `fromStatus` | [`SubscriptionStatus!`](#subscriptionstatus) | — |
| `toStatus` | [`SubscriptionStatus!`](#subscriptionstatus) | — |
| `source` | [`StatusChangeSource!`](#statuschangesource) | — |
| `reason` | `String` | Cancellation reason, when one was given. |
| `changedAt` | `DateTime!` | — |

### PriceChange

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | `ID!` | — |
| `oldAmount` | `Money!` | — |
| `newAmount` | `Money!` | — |
| `source` | [`PriceChangeSource!`](#pricechangesource) | — |
| `changedAt` | `DateTime!` | — |

### SubscriptionEdge

| Campo | Tipo | Descrição |
| - | - | - |
| `cursor` | `String!` | — |
| `node` | [`Subscription!`](#subscription) | — |

### SubscriptionConnection

| Campo | Tipo | Descrição |
| - | - | - |
| `edges` | [`[SubscriptionEdge!]!`](#subscriptionedge) | — |
| `nodes` | [`[Subscription!]!`](#subscription) | — |
| `pageInfo` | [`PageInfo!`](#pageinfo) | — |
| `totalCount` | `Int!` | Rows matching the filter, regardless of the page. |

### SubscriptionOrder

| Campo | Tipo | Descrição |
| - | - | - |
| `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

| Campo | Tipo | Descrição |
| - | - | - |
| `cursor` | `String!` | — |
| `node` | [`SubscriptionOrder!`](#subscriptionorder) | — |

### SubscriptionOrderConnection

| Campo | Tipo | Descrição |
| - | - | - |
| `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.

| Campo | Tipo | Descrição |
| - | - | - |
| `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

| Campo | Tipo | Descrição |
| - | - | - |
| `cursor` | `String!` | — |
| `node` | [`Customer!`](#customer) | — |

### CustomerConnection

| Campo | Tipo | Descrição |
| - | - | - |
| `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»).

| Campo | Tipo | Descrição |
| - | - | - |
| `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

| Campo | Tipo | Descrição |
| - | - | - |
| `cursor` | `String!` | — |
| `node` | [`PlanGroup!`](#plangroup) | — |

### PlanGroupConnection

| Campo | Tipo | Descrição |
| - | - | - |
| `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.

| Campo | Tipo | Descrição |
| - | - | - |
| `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

| Campo | Tipo | Descrição |
| - | - | - |
| `cursor` | `String!` | — |
| `node` | [`Plan!`](#plan) | — |

### PlanConnection

| Campo | Tipo | Descrição |
| - | - | - |
| `edges` | [`[PlanEdge!]!`](#planedge) | — |
| `nodes` | [`[Plan!]!`](#plan) | — |
| `pageInfo` | [`PageInfo!`](#pageinfo) | — |
| `totalCount` | `Int!` | — |

### Box

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

| Campo | Tipo | Descrição |
| - | - | - |
| `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

| Campo | Tipo | Descrição |
| - | - | - |
| `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

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | `ID!` | — |
| `shopifyVariantId` | `ID!` | — |
| `kind` | [`BoxOptionKind!`](#boxoptionkind) | — |

### BoxTier

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | `ID!` | — |
| `basis` | `String!` | quantity \| amount. |
| `threshold` | `Money!` | — |
| `discountType` | `String!` | percent \| fixed. |
| `value` | `Money!` | — |

### BoxEdge

| Campo | Tipo | Descrição |
| - | - | - |
| `cursor` | `String!` | — |
| `node` | [`Box!`](#box) | — |

### BoxConnection

| Campo | Tipo | Descrição |
| - | - | - |
| `edges` | [`[BoxEdge!]!`](#boxedge) | — |
| `nodes` | [`[Box!]!`](#box) | — |
| `pageInfo` | [`PageInfo!`](#pageinfo) | — |
| `totalCount` | `Int!` | — |

### PageInfo

| Campo | Tipo | Descrição |
| - | - | - |
| `hasNextPage` | `Boolean!` | — |
| `endCursor` | `String` | Pass as `after` to fetch the next page. Null on the last page. |

***

## Inputs

### SubscriptionItemInput

| Campo | Tipo | Descrição |
| - | - | - |
| `planId` | `ID!` | The Plan (product offering) id — see `plans`. |
| `quantity` | `Int!` | — |

### AddressInput

| Campo | Tipo | Descrição |
| - | - | - |
| `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

| Campo | Tipo | Descrição |
| - | - | - |
| `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

| Campo | Tipo | Descrição |
| - | - | - |
| `subscriptionId` | `ID` | — |
| `customerEmail` | `String` | — |
| `type` | [`OrderType`](#ordertype) | — |
| `shopifyOrderId` | `ID` | — |
| `createdAfter` | `DateTime` | — |
| `createdBefore` | `DateTime` | — |

### CustomerFilter

| Campo | Tipo | Descrição |
| - | - | - |
| `emailContains` | `String` | Substring match on the email (case-insensitive). |
| `shopifyCustomerId` | `ID` | — |

### PlanGroupFilter

| Campo | Tipo | Descrição |
| - | - | - |
| `status` | [`PlanStatus`](#planstatus) | — |
| `type` | [`PlanGroupType`](#plangrouptype) | — |

### PlanFilter

| Campo | Tipo | Descrição |
| - | - | - |
| `status` | [`PlanStatus`](#planstatus) | — |
| `shopifyVariantId` | `ID` | — |
| `planGroupId` | `ID` | — |

### BoxFilter

| Campo | Tipo | Descrição |
| - | - | - |
| `status` | [`PlanStatus`](#planstatus) | — |
| `type` | [`BoxType`](#boxtype) | — |

***

## Enums

### CancelReason

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

| Valor | Descrição |
| - | - |
| `TOO_EXPENSIVE` | — |
| `PRODUCT_PILED_UP` | — |
| `WANT_ANOTHER_PRODUCT` | — |
| `DELIVERY_PROBLEMS` | — |
| `NO_LONGER_NEEDED` | — |
| `OTHER` | — |

### UserErrorCode

| Valor | Descrição |
| - | - |
| `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

| Valor | Descrição |
| - | - |
| `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

| Valor | Descrição |
| - | - |
| `CREATED_AT` | — |
| `UPDATED_AT` | — |
| `NEXT_PAYMENT_DATE` | — |

### SubscriptionItemRole

| Valor | Descrição |
| - | - |
| `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

| Valor | Descrição |
| - | - |
| `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

| Valor | Descrição |
| - | - |
| `MERCHANT` | — |
| `CUSTOMER` | — |
| `API` | A mutation of this API (SUB-168). |

### OrderType

| Valor | Descrição |
| - | - |
| `FIRST` | The first cycle, charged at checkout. |
| `RENEWAL` | — |

### FrequencyType

| Valor | Descrição |
| - | - |
| `DAYS` | — |
| `WEEKS` | — |
| `MONTHS` | — |

### PlanPriceType

| Valor | Descrição |
| - | - |
| `FIXED` | A fixed amount per cycle. |
| `PERCENT` | A percentage off the variant's live Shopify price. |

### PlanStatus

| Valor | Descrição |
| - | - |
| `ACTIVE` | — |
| `ARCHIVED` | — |

### PlanGroupType

| Valor | Descrição |
| - | - |
| `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

| Valor | Descrição |
| - | - |
| `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

| Valor | Descrição |
| - | - |
| `FIXED` | — |
| `SIZES` | — |
| `RANGE` | — |

### BoxOptionKind

| Valor | Descrição |
| - | - |
| `ELIGIBLE` | A product the shopper can put in the recurring box. |
| `ONE_TIME_UPSELL` | A one-time add-on offered before confirming. |

***

## Escalares

| Tipo | Descrição |
| - | - |
| `DateTime` | Data e hora ISO-8601 em UTC, por exemplo `"2026-11-02T13:00:00.000Z"`. |
| `Money` | Valor decimal como string com duas casas, por exemplo `"18500.00"`. A moeda vai no campo `currency` do mesmo objeto. |
| `ID` | Identificador opaco da Reval. Use sempre o que a API devolveu. |
| `Int` | Inteiro. |
| `String` | Texto. |
| `Boolean` | `true` ou `false`. |


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