This is the API documentation for ReturnZap. Here you can explore all the available queries, mutations, and data types.

Which amount do I actually refund?

Return.suggestedRefund(returnItemIds:) returns several MoneySet values. Only one of them is the amount to pay out.

Field	Meaning
availableForRefundSet	Gross ceiling for the selected items — the most this selection can be refunded. It does not report the remaining refundable amount of the whole order. Never pay this out.
suggestedRefundSet	Gross suggested refund, before outstanding handling and restocking fees.
netRefundPayableSet	The payable amount. suggestedRefundSet minus the handling and restocking fees still outstanding on the return, clamped at zero.

Pass netRefundPayableSet to returnRefund(refundFullAmount:).

The fee arguments on returnRefund — handlingFee and restockingFee — are record-only. They are stored on the return for reporting and do not reduce refundFullAmount. Sending suggestedRefundSet together with a fee argument over-refunds the customer by the fee. The same applies to returnCreateStoreCredit(amount:). One mode caveat: restockingFee is only recorded when the return's restocking fee is configured once per return; in once-per-item mode the argument is ignored and Return.actualRestockingFeeCharged stays unchanged.

Record-only does not mean optional. netRefundPayableSet is computed as suggestedRefundSet minus the fees still outstanding — the suggested fee minus what has already been recorded as charged. If you deduct a fee by paying out netRefundPayableSet but never send handlingFee / restockingFee, nothing is recorded, and the next partial refund on the same return will subtract the very same fee again and short-change the customer. Always send the fee amounts the deduction represents — that is what handlingFeeSuggestedSet and restockingFeeSuggestedSet are for, and it is what the ReturnZap admin UI does on every refund.

The one exception is a clamped payout: if netRefundPayableSet comes back 0.00 while suggestedRefundSet is positive, the outstanding fees exceed this selection's gross refund, so only part of the fee is actually being withheld. Do not send the full suggested fee amounts there — the recorded fee would exceed what was withheld, the return would show no outstanding fee, and the next partial refund would pay out too much. Recorded fees are cumulative maxima (Return.actualHandlingFeeCharged / Return.actualRestockingFeeCharged), so in the clamped case send fee amounts that grow those recorded values by at most this selection's suggestedRefundSet — or resolve the fee-bearing selection last, where the clamp cannot occur.

Optional shipping reimbursement and store-credit incentives are not folded into netRefundPayableSet; add them yourself if your flow offers them. For a store-credit incentive, adding it to amount alone is not enough: also pass it as returnCreateStoreCredit(bonusCredit:). When the shop issues credit as Shopify account credit, only the bonusCredit portion is excluded from the order's refundable balance — an incentive folded silently into amount consumes that balance and can shrink a later refund on the same order.

shopMoney vs presentmentMoney

Every MoneySet is { shopMoney, presentmentMoney }, and each Money is { amount, currencyCode }. Presentment is the currency the customer paid in; shop is the store's own currency.

returnRefund validates refundFullAmount against Shopify's presentment transaction totals, so send presentmentMoney.amount with refundCurrency: presentmentMoney.currencyCode. Use shopMoney only when aggregating across orders in a single currency — never mix the two in one total.

Worked example

suggestedRefund requires returnItemIds. It returns null when the list is empty, when none of the ids resolve to a return item on this return with a Shopify line item, or when the underlying Shopify call fails. A null is never "the refund is zero" — treat it as "unknown, do not refund" and retry.

query SuggestedRefund(: ID!, : [ID]!) {
  getReturn(returnId: ) {
    id
    suggestedRefund(returnItemIds: , refundShipping: false) {
      availableForRefundSet { presentmentMoney { amount currencyCode } }
      suggestedRefundSet    { presentmentMoney { amount currencyCode } }
      netRefundPayableSet   { presentmentMoney { amount currencyCode } }
      handlingFeeSuggestedSet   { presentmentMoney { amount } }
      restockingFeeSuggestedSet { presentmentMoney { amount } }
    }
  }
}

Then feed netRefundPayableSet.presentmentMoney straight into the mutation:

mutation Refund(
  : ID!
  : [ID!]!
  : Decimal!      # netRefundPayableSet.presentmentMoney.amount
  : String!     # netRefundPayableSet.presentmentMoney.currencyCode
  # The fee args are optional in the schema, but always send both (0 if none) — see
  # above, including the clamped-payout exception when netRefundPayableSet is 0.00.
  : Decimal! # handlingFeeSuggestedSet.presentmentMoney.amount
  : Decimal! # restockingFeeSuggestedSet.presentmentMoney.amount
) {
  returnRefund(
    returnId: 
    returnItemIds: 
    refundShipping: false
    refundFullAmount: 
    refundCurrency: 
    handlingFee: 
    restockingFee: 
    notifyCustomer: true
  ) {
    error
    refund {
      shopifyRefundId
      requestedTotalRefundAmount
      requestedCurrencyCode
      presentmentTotalAmountRefunded
    }
  }
}

Reading a RefundType

• requestedTotalRefundAmount / requestedCurrencyCode — exactly what you passed as refundFullAmount / refundCurrency, in presentment currency. Available immediately.
• presentmentTotalAmountRefunded — the net cash Shopify refunded. This is the settlement figure, and it is populated asynchronously: Shopify can delay totalRefundedSet until the underlying transactions settle, so a completed refund can legitimately read 0.00 for minutes or longer. A nightly backfill re-fetches recent refunds still sitting at zero. Do not treat 0.00 here as "the refund failed" — check requestedTotalRefundAmount and the error field on the mutation instead.
• shopTotalAmountRefunded and the shop* breakdown carry the same figures converted to the shop's currency, with the same delay.
• currencyCode and totalAmountRefunded are deprecated aliases of presentmentCurrencyCode and presentmentTotalAmountRefunded.

Confirming a resolution

returnRefund and returnCreateStoreCredit commit in one transaction. The reliable immediate signals are the mutation's own payload and the return's collections:

• returnRefund { error } — empty string on success; a locale key such as refundMutation.refundIntegrationError on failure.
• Return.refunds — the new RefundType is present as soon as the mutation returns.
• Return.storeCredits — likewise for store credit.

Return.resolvedStatus (RESOLVED / PARTIALLY_RESOLVED / UNRESOLVED) is recomputed in the same transaction, but the return object embedded in the mutation payload is serialized from the copy loaded before the resolution, so it can still show the pre-refund value. Re-query getReturn if you need resolvedStatus, or use refunds as the immediate signal.

Duplicate resolutions are already rejected server-side

You do not need to build your own idempotency guard against double-refunding. Every financial path takes a row lock on the return, then re-reads the items:

• returnRefund and returnCreateStoreCredit only accept return items that are not already resolved. A retry against an already-refunded item fails with refundMutation.returnItemsNotEligibleForRefund (or returnCreateStoreCreditMutation.returnItemsNotEligibleForStoreCredit), not a second payout.
• Crossing the paths is rejected too: crediting an item that already has a refund, or refunding an item that already has store credit, fails on the loser of the lock.

Never retry blindly on a non-empty error. refundMutation.refundIntegrationError covers both a harmless rejection (a concurrent duplicate lost the row lock — no money moved) and a reconciliation failure after Shopify already moved money, and the two are not distinguishable from the response. On any error, re-query getReturn { refunds { … } }. A matching refund present means the payout landed — do not retry. A matching refund absent is not proof that no money moved: in the reconciliation-failure case ReturnZap cannot attribute the new Shopify refund and deliberately records nothing, so the payout exists in Shopify but never appears in refunds. Before retrying, check the order's refund list in Shopify admin (or via the Shopify API); if a refund for the amount is already there, reconcile manually with ReturnZap support instead of retrying.

Refunding never restocks

Issuing a refund or store credit does not put inventory back. Restocking is a separate, explicit, irreversible call, per item:

mutation Restock(: ID!, : [ID!]!, : ID!) {
  returnDispose(
    returnId: 
    returnItemIds: 
    dispositionAction: RESTOCK
    shopifyLocationId: 
  ) {
    error
    return { id }
  }
}

Items that were rejected or marked missing at receiving cannot be restocked; the mutation restocks the remaining valid items and returns disposeMutation.itemNotRestockable alongside the payload as a partial-success caveat.

What returns(query:) matches

The free-text query argument on returns (and the deprecated dashboardReturns) runs a PostgreSQL full-text search over exactly these seven columns:

Matched field	Exposed on Return as
customer_first_name	customerFirstName
customer_last_name	customerLastName
customer_email	customerEmail
shopify_order_number	shopifyOrderNumber
rma_number	rmaNumber
tracking_number	trackingNumber
shopify_order_id	shopifyOrderId

Nothing else is searched — not notes, not SKUs, not product titles, not addresses. It is a PostgreSQL full-text match using the english configuration, not a substring match: partial fragments and prefixes do not hit, and all terms must match. Terms are also stemmed and stop-word filtered — inflections of the same English word share a match (returned finds returning), and a term that is an English stop word (a customer named May, for example) is dropped entirely and can make a row unfindable by that field alone. Do not treat it as exact token matching. Matching is a filter only — results are ordered by sortBy (default -returnDate), not by relevance.

Read the order number off Return.shopifyOrderNumber. Return.orderNumber still exists as a deprecated alias of the same value — new integrations should not use it.

RMA number formats

Generated RMA numbers come in two shapes, and which one a shop uses is a per-shop setting. You cannot tell them apart from a single value's shape alone.

• Short (the default): 1.1001 — an unpadded per-order return counter and the Shopify order name with # stripped, no date.
• Long: 0001.1001.20260613 — the counter zero-padded to four digits, the order name, and YYYYMMDD of creation.

A shop can also override the RMA number entirely when approving a return: any custom value is accepted (truncated to 45 characters), so do not build a parser that rejects values outside the two generated shapes.

The return-label barcode

The barcode printed on the RMA slip does not always encode the RMA number. It encodes whichever value the shop configured, one of four:

Setting	Barcode contents
NONE	No barcode is rendered at all.
SHOPIFY_ORDER_NUMBER	Return.shopifyOrderNumber
SHOPIFY_ORDER_ID	Return.shopifyOrderId
RMA_NUMBER	Return.rmaNumber, with any apostrophes stripped

A scanner-driven lookup must therefore try the scanned string against the free-text returns(query:) search rather than assuming it is an RMA number — all three non-empty settings encode a field that search covers. Note the RMA_NUMBER caveat: the search indexes the stored rmaNumber verbatim, so for the rare RMA number containing an apostrophe the scanned barcode is not byte-identical to the stored value. Fall back to matching Return.rmaNumber client-side if a scan comes back empty.

Barcodes are Code 128, which cannot encode every character. If the configured value contains a character outside that set — possible with RMA_NUMBER when a custom RMA carries, say, an accented letter — the slip renders without a barcode rather than failing, so a non-NONE setting does not guarantee a barcode on every slip.

Return.systemStage is an Int, and its order is not workflow order

systemStage is typed Int, not an enum. Its values are:

Value	Meaning
1	Automatically approved
2	Pending approval
3	Approved
4	Rejected
5	Received

Do not sort or compare on this number. The numbers are storage ids, not workflow positions — internally the workflow order is a separate remapping in which pending approval comes first and automatic approval sits between approved and received. Treat systemStage as a categorical label.

systemStage is also null for a return sitting in a shop-defined custom stage. Use stageId plus the shop's stage list to resolve the label:

query Stages {
  getMyShop {
    stages { id label systemStage behavior }
  }
}

Match Return.stageId against id in that list. Note the type mismatch: Stage.systemStage on that list is the SystemStage enum (AUTOMATICALLY_APPROVED, PENDING_APPROVAL, APPROVED, REJECTED, RECEIVED), while Return.systemStage is the Int above — the table maps between them. A custom stage has systemStage: null but may still behave like a system stage: Stage.behavior carries the effective SystemStage enum for a custom stage configured to act like one (for example a shop's own "received" stage), and is the field to read when you care about semantics rather than identity. Return.stageLabel is a snapshot of the stage's label taken when the return entered the stage: if the merchant later renames the stage, stageLabel keeps the old text while stages[].label reflects the rename. Map stageId against the stage list when you need the current display name. statusId and statusLabel are older aliases of stageId and stageLabel.

Return.availableActions

availableActions is a list of ProcessingStatusAction tokens that partitions returns into two coarse families — draft and live. It does not check per-mutation eligibility: a fully resolved return still reports POST_ACTIVATION_ACTIONS even though a further refund would be rejected. The complete set of values it can return:

Token	Meaning
POST_ACTIVATION_ACTIONS	The return is live (not a draft); the approve / receive / refund / dispose family of mutations applies, subject to each mutation's own validation. This is returned alone, never alongside the draft tokens.
DISCARD	Draft only — the draft can be discarded. Not offered once its Shopify return has synced.
CONVERT_SHIPPING	Draft only — the shipping choice can still be converted.
RETRY	Draft only — a failed activation step can be retried.
WAIVE_BALANCE	Draft only — an outstanding exchange balance can be waived.
RESEND_BALANCE_INVOICE	Draft only — the balance invoice can be re-sent.

A draft never reports POST_ACTIVATION_ACTIONS: the post-activation mutations exclude drafts and would report the return as not found.

Disposition enums

returnDispose takes two mutually exclusive enums. Prefer dispositionAction — it is the business-level intent, and ReturnZap maps it to what Shopify records.

DispositionAction (pass one of these):

Value	Recorded in Shopify as
RESTOCK	RESTOCKED — the only value that returns inventory to stock
REFURBISH	PROCESSING_REQUIRED
RECYCLE	NOT_RESTOCKED
DESTROY	NOT_RESTOCKED
DONATE	NOT_RESTOCKED
LIQUIDATE	NOT_RESTOCKED
RESELL	NOT_RESTOCKED

DispositionType is the raw Shopify-level value (MISSING, PROCESSING_REQUIRED, NOT_RESTOCKED, RESTOCKED) and is accepted for backwards compatibility. Supply one of the two arguments: supplying neither fails with disposeMutation.invalidDispositionType, and if both are supplied dispositionAction wins and dispositionType is silently ignored — do not send both. shopifyLocationId is required, and every id in returnItemIds must belong to the given return. Disposition is irreversible.

Item vendor

For newly created return items, vendor is recorded from the Shopify order line at purchase time. It does not follow the product if the merchant later reassigns the product's vendor. Older return items may contain values populated by historical maintenance.

Automatic population begins with the 2026-08-25 release noted in the changelog. This release does not run a backfill, so older return items that were not populated by historical maintenance remain empty. Around the release itself the boundary is approximate rather than exact — a rolling deploy means some returns created that day still read empty.

An empty vendor is therefore never authoritative: it means the Shopify line carried no vendor, or the return item was not populated, and the API cannot tell you which. Do not read "" as evidence that a product has no vendor.

Migrating off deprecated fields

dashboardReturns → returns. Same arguments, same DashboardResponse. The old name was a misnomer: it returns a filtered, paginated list of returns, not dashboard aggregates. Rename the field and nothing else.

archiveReturns → returnUpdateStatus. The arguments differ:

archiveReturns	returnUpdateStatus
returnIds: [ID]! — no length limit	returnIds: [ID]! — capped at 10 ids per call; may be empty when filters is supplied
archive: Boolean!	isArchived: Boolean! (renamed)
—	filters: FiltersInput — archive everything matching a filter instead of an explicit id list
returns success	returns success and affectedReturnIds

Passing neither filters nor a non-empty returnIds is an error, and ids for returns outside your shop are silently not matched — so read affectedReturnIds rather than assuming every id you sent was archived. The two argument styles are mutually exclusive in effect: whenever returnIds is non-empty, filters is ignored entirely — to archive by filter, send returnIds: []. Batches larger than ten ids are rejected; chunk them or switch to filter mode.

The two are not behaviourally identical: archiveReturns skips draft returns, returnUpdateStatus does not. If your id list or filter can include drafts, a straight rename will start archiving them. Filter drafts out of returnIds yourself — adding filters alongside a non-empty id list does nothing — or use filter mode with filters: { processingStatus: [...] } and an empty returnIds.

Other deprecated fields worth migrating while you are here: suggestionRefund → suggestedRefund, handlingFeeCharged → originalHandlingFeeCharged / actualHandlingFeeCharged, restockingFeeCharged → originalRestockingFeeCharged / actualRestockingFeeCharged, shippedTo → warehouseName, appliedRules → appliedRulesDetailed, next/previous → nextReturn/previousReturn.

The event catalog

There are exactly two events:

Event	Fires when
return_created	A return becomes live.
return_updated	A live return changes one of the fields carried in the payload below.

Deliveries are queued on transaction commit, and events are coalesced per return per transaction: several saves of the same return in one business operation produce one delivery, and if both events are pending for the same return, only return_created is sent. Do not expect one delivery per field change. A change that only touches fields outside the payload usually delivers nothing; return_date is the exception and can fire return_updated without appearing in the body.

Drafts never deliver. A return in a draft state is skipped entirely; it sends return_created when it is activated, not when the draft row appeared.

Two other cases are silent. Unarchiving a return does not send return_updated (archiving does). Pre-fulfillment and manual withdrawals never send webhooks.

Webhooks are a plan feature. If the shop's subscription does not include webhooks, nothing is delivered, and no error is surfaced to the API caller.

The delivered request

Every delivery is an HTTP POST with Content-Type: application/json and a body of this shape. Note the keys are snake_case, unlike the GraphQL API's camelCase:

{
  "event": "return_created",
  "content": {
    "shop":   { "id": "42", "uuid": "…", "url": "example.myshopify.com" },
    "return": { "id": "12345", "uuid": "…", "rma_number": "1.1001", "…": "…" }
  },
  "trace_id": "…",
  "call_id": "…",
  "webhook_url": "https://example.com/hooks/returnzap",
  "webhook_id": "…"
}

content.return is a snake_cased projection of the GraphQL Return type — a fixed subset, not the whole type. It carries the identity and status fields (id, uuid, rma_number, customer_email, customer_first_name, customer_last_name, shopify_order_id, shopify_order_number, rma_form_url, stage_id, stage_label, system_stage, created_at, is_archived, approval_required, rejected_at, rejection_reason, gift_return, gift_return_email_address, no_shipping_required, exchange_balance_due, return_item_types, return_type_labels), the shipping fields (tracking_number, shipping_method, shipment_carrier_name, shipment_service_name), the customer_address / destination_address / gift_return_address objects, a shipment object holding tracking_url, an exchange_items array, and an items array. Each item carries its own identifiers, quantities, reason and condition, pre_tax_price_set / post_tax_price_set money sets, its exchange_item, and the shopper's answers.

Ids arrive as strings, including content.shop.id and content.return.id.

The same field semantics documented elsewhere in these docs apply here — in particular system_stage is a categorical Int whose order is not workflow order, and stage_label is a snapshot taken when the return entered the stage.

The four top-level fields outside content are added by the delivery layer:

Field	Meaning
trace_id	Identifies the originating business operation. Stable across retries — quote it to support.
call_id	Unique per delivery attempt. A retry carries a new one, so it is not a deduplication key.
webhook_url	The endpoint this delivery was addressed to.
webhook_id	The endpoint's id.

Treat deliveries as best-effort and possibly duplicated, and possibly out of order. Each body is a snapshot: upsert on content.return.id (or uuid). Do not drop a delivery because event plus return id already arrived — later updates reuse that pair. call_id changes on every attempt, and trace_id names the originating operation (callers can reuse X-Trace-Id), so neither identifies one delivery.

Verifying the signature

Every delivery carries X-ReturnZap-Signature: the lowercase hex HMAC-SHA256 of the raw request body, keyed by the endpoint's signing secret (UTF-8). There is no timestamp, no version prefix, and no other component in the header value.

The body is serialized once as compact, key-sorted JSON and those exact bytes are both signed and sent, so verify against the raw bytes you received — parsing the JSON and re-serializing it will not reproduce the signature reliably.

import hashlib
            import hmac
            
            
            def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
                expected = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
                return hmac.compare_digest(expected, signature_header or "")
            

const crypto = require('node:crypto')
            
            function verify(rawBody, signatureHeader, secret) {
              const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
              const a = Buffer.from(expected, 'utf8')
              const b = Buffer.from(signatureHeader || '', 'utf8')
              return a.length === b.length && crypto.timingSafeEqual(a, b)
            }
            

Most web frameworks hand you a parsed body by default. Capture the raw body explicitly (express.raw({ type: 'application/json' }), Django's request.body before any parsing, and so on) and compare in constant time, as above.

The signing secret is generated when the endpoint is created and shown once. Rotating it takes effect immediately — the previous secret stops validating on the next delivery. Copy the new secret and deploy it; there is no overlap window, so deliveries between rotate and deploy fail signature checks. If the endpoint is also configured with HTTP Basic Auth, deliveries additionally carry a standard Authorization: Basic header; the signature is unaffected.

This signing scheme is not final. The Warehouse partner API uses a newer, timestamped scheme, and whether the two converge is an open question. Keep your verification logic in one place so it can be updated.

Retries

Each attempt has a 10-second timeout. If the endpoint answers with a 4xx or 5xx status, the delivery is retried up to 5 times with exponential backoff from a 30-second base: 30s, 60s, 120s, 240s, 480s — six attempts in total, spanning roughly 15 minutes. Retries repeat the same content with a fresh call_id and the original trace_id.

Two limits are worth designing around:

• A connection failure or a timeout is not retried. Only a 4xx or 5xx status schedules a retry; if your endpoint is unreachable or too slow to answer within 10 seconds, that delivery is dropped. Answer 2xx immediately and do the work asynchronously.
• After the final retry the delivery is abandoned — there is no dead-letter queue and no self-serve replay. Webhooks are a latency optimization, not a system of record: reconcile against the API periodically rather than assuming every event arrived.

Configuring an endpoint

There are two kinds of endpoint, and both deliver identically:

• Customer-managed. Configured in HQ under Settings → Integrations: URL, which of the two events to send, an enable/disable toggle, optional Basic Auth credentials, and the signing secret with a rotate action. Requires the HQ Can Modify Settings permission — without it the controls are hidden. At most one per shop — a database constraint enforces it. Clearing the URL deletes the endpoint.
• Support-managed. Additional endpoints ReturnZap support configures on request, one per distinct URL, not visible or editable in HQ.

A delivery goes to every enabled endpoint whose event list includes the event, so a shop with both kinds receives the event on both.

Creating a token

Merchants issue their own tokens — no support ticket needed. In HQ, go to Settings → Integrations → API tokens and choose Create token. The only input is an optional label (it defaults to API Token); use it to name the integration the token belongs to.

The plaintext token is displayed once, immediately after minting, and is never retrievable afterwards. Copy it straight into your secret store. It looks like rz_prod_ followed by 32 hex characters.

The card also supports editing a token's label and revoking a token. Revocation takes effect on the token's next request and cannot be undone — issue a new token and migrate rather than expecting to restore one. The token list shows each token's label, last four characters, creation date, who created it, and when it was last used.

Minting requires the API access plan feature and the HQ Can Modify Settings permission. Losing the feature automatically revokes every active token from this card — they disappear from the list and cannot be restored.

Using a token

Send it as a bearer token on every request:

POST /graphql/admin HTTP/1.1
Host: api.returnzap.com
Content-Type: application/json
Authorization: Bearer rz_prod_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tokens minted from this card are full-access and non-expiring. There is no rotation action, no expiry to configure, and no narrower scope to request: the card issues one kind of credential. (Narrower scopes and expiry exist inside the system for other credential types — do not build an integration that expects to obtain them here.)

Two consequences of "full access" are worth stating plainly:

• A token carries shop-wide authority over return data. Per-user permission checks do not apply to token-authenticated requests, so there is no way to hand out a read-only or returns-only token from here. Keep it server-side, in a secret manager — never ship it to a browser, a mobile app, or a shared CI log. The one thing a token deliberately cannot do is manage credentials: minting, relabelling, revoking, and rotating tokens require a signed-in HQ user, so a leaked token cannot mint itself a successor.
• A token is bound to the shop it was minted for. To integrate with several shops, mint a token per shop.

The last used column is stamped at most once every five minutes, so it is a liveness hint, not an audit log. Do not use it to prove a token was or was not used at a given moment.

The separate Merchant MCP credential on the same settings page is a different flow with its own lifecycle; it does not authenticate against this API.

How a deprecation is signalled

A deprecated query, mutation, or field carries a deprecationReason. That reason is visible through GraphQL introspection and rendered in these docs, so your tooling can detect deprecations without reading release notes. Treat it as explanatory metadata — it often names a replacement, but it may be empty or say only that the member is unused. There is no other signal: no response header, no sunset date embedded in the schema.

Deprecation alone changes nothing at runtime. The field keeps working, unchanged, for the whole window below.

The windows

• 90 days of sunset from the deprecation date. During this period the deprecated member continues to behave exactly as before. This is the window to migrate in.
• Removable at 180 days, and only then. A deprecated member is removed no earlier than 180 days after its deprecation date, and only once measured usage has reached zero — a field still carrying live traffic stays past 180 days rather than breaking callers.
• Every removal is announced in the changelog below before it ships. A member disappearing without a changelog entry is a bug; report it.

Migrate within the sunset window rather than at the deadline, and read "Enums, stages, and deprecated fields" first: some replacements are not behaviour-identical to the member they replace (archiveReturns → returnUpdateStatus differs on draft returns, for one), so a blind rename can change what your integration does.

Changelog

Newest first. This log begins in August 2026, seeded with the most recent notable schema changes; it is not a complete history of the API.

Date	Change
2026-08-25	Began automatically populating vendor on newly created return items. No backfill in this release; older items may contain historical values, and an empty value stays ambiguous. See "Item vendor".
2026-08-12	Added SuggestedRefundType.netRefundPayableSet — the refund amount to actually pay out, suggestedRefundSet minus outstanding handling and restocking fees. See "Money semantics".
2025-11-03	Deprecated the dashboardReturns query → use returns. Same arguments, same response type.
2024-10-24	Deprecated the archiveReturns mutation → use returnUpdateStatus. Arguments differ, and the two treat draft returns differently.