Subscriptions & Memberships has a GraphQL API for headless storefronts and integrations. It is the only API: there is no REST. This page lists what is there and shows the calls you will use most. The schema ships with salesigniter/releasesubscriptions2, so every field below appears in your store’s GraphQL schema once the extension is installed.
Who can call what #
- Fields that start
sisubMy...(and the customer mutations) need a customer token. They only ever see the signed in customer’s own data. - The other
sisub...queries and mutations are for staff and need an admin or integration token whose role has the Subscriptions resources. - Product and cart additions (
sisub_plans,sisub) are public like any catalog field.
Showing the plans on a product #
ProductInterface gets three fields.
query {
products(filter: { sku: { eq: "SISUB-E2E-COFFEE" } }) {
items {
name
sisub_enabled
sisub_offer_mode
sisub_plans {
key label interval_label price_mode price_value
trial_count trial_unit signup_fee max_cycles is_default
}
}
}
}sisub_offer_mode is OPTIONAL (the customer chooses) or SUBSCRIPTION_ONLY.
Subscribing: add to cart #
Add the product to the cart with selected_options, using the base64 encoded strings sisub/mode/subscribe and sisub/plan/<key>, where <key> is the plan’s key. Read the plan back from the cart line:
query {
cart(cart_id: "Zk3x9QJ0example") {
items {
product { name }
sisub { mode plan { label interval_label signup_fee } }
}
}
}mode is subscribe for a new subscription, renewal for a line created by a renewal and recovery for a payment recovery cart. The customer then pays with the normal checkout mutations; cards are saved for renewals.
A customer’s subscriptions #
query {
sisubMySubscriptions(status: [ACTIVE, PAST_DUE], pageSize: 20, currentPage: 1) {
items {
id reference status status_label plan_label
amount { value currency }
next_billing_at payment_label
available_actions
items { sku name qty unit_price { value } }
}
total_count
}
}sisubMySubscription(id:) returns one. Statuses are PENDING, TRIAL, ACTIVE, PAST_DUE, ON_HOLD, PAUSED, PENDING_CANCEL, CANCELLED and EXPIRED. available_actions lists what the customer may do now: PAUSE, RESUME, CANCEL, CANCEL_AT_PERIOD_END, UNDO_CANCEL.
Customer actions #
| Mutation | What it does |
|---|---|
| — | — |
sisubPauseSubscription(id, cycles) | Pause for a number of billing periods. |
sisubResumeSubscription(id) | Start again now. |
sisubCancelSubscription(id, reason, at_period_end) | Cancel, by default at the period end. |
sisubUndoCancelSubscription(id) | Undo a cancel at period end. |
sisubSkipNextRenewal(id) | Skip the next period. |
sisubRenewMySubscriptionNow(id) | Pay for the next period now. |
sisubChangeSubscriptionPlan(id, plan_key) | Move to another plan of the product, from the next renewal. |
sisubSetSubscriptionPaymentMethod(id, public_hash) | Use another saved card. |
sisubAddToNextRenewal(id, sku, qty) / sisubRemoveFromNextRenewal(id, item_id) | Add or remove a one-time extra. |
sisubSwapSubscriptionItem(id, item_id, choice) | Swap a line for an allowed choice. |
sisubAcceptRetentionOffer(id, offer, reason, cycles) | Take a save offer before cancelling. |
sisubStartRecoveryCheckout(id) | Start a cart that pays a failed renewal. |
The helper queries sisubMyCancelOffers, sisubMyPlanChoices, sisubMySavedCards, sisubMySwapChoices and sisubCancelReasons return what to show in the cancel flow, the plan chooser and the card picker.
Memberships and store credit #
query {
sisubMyMemberships {
id name type status credit_balance { value currency } queue_slots queue_out
ledger { type amount comment created_at }
}
sisubMyCreditBalance { value currency }
}To spend credit, applySisubCreditToCart(cart_id) and removeSisubCreditFromCart(cart_id). Membership type is credit, queue, group or mixed; status is active, suspended, ended or cancelled. Ledger entry types are grant, renewal_grant, spend, cancel_restore, refund, adjust and expire.
Rental queue #
| Field | Who | What it does |
|---|---|---|
| — | — | — |
sisubMyQueue | Customer | The queue, the titles out now, slots and whether a send is possible. |
sisubAddToQueue(sku), sisubRemoveFromQueue(item_id), sisubReorderQueue(item_ids) | Customer | Manage the queue. |
sisubQueue(customer_id) | Admin | One member’s queue. |
sisubAdminQueueAdd, sisubAdminQueueMove, sisubAdminQueueRemove | Admin | Change a member’s queue. |
sisubQueueSend(item_id, serials, source_code), sisubQueueSendNext(customer_id) | Admin | Send a title or the next available one. |
sisubQueueReturn(loan_id, serials), sisubQueueReturnBySerials(serials), sisubQueueMarkLost(loan_id, note) | Admin | Record returns and losses. |
sisubQueueLoans(filter), sisubQueuePickList(limit) | Admin | The Loans and Pick list screens. |
A loan has the status out, returned, lost or cancelled, its serials, the sent and due-back dates and, with the rental bridge, the reservation that holds the unit.
Administration #
| Field | What it does |
|---|---|
| — | — |
sisubSubscriptions(filter, sort, pageSize, currentPage) / sisubSubscription(id) | Search and read any subscription, with its schedule and events. |
sisubRenewalLog(filter) | The Renewals Log. |
sisubCreateSubscription(input) / sisubUpdateSubscription(id, input) / sisubDeleteSubscription(id) | Create, change or delete. |
sisubTransitionSubscription(id, action, reason, cycles) | Pause, resume or cancel on a customer’s behalf. |
sisubRenewNow(id) | Charge the next renewal now. |
sisubAdminSwapSubscriptionItem(id, item_id, choice) | Change a line to another product. |
sisubMemberships(filter) / sisubMembership(id) | Search and read memberships. |
sisubCreateMembership, sisubUpdateMembership, sisubDeleteMembership | Manage memberships. |
sisubAdjustCredit(membership_id, new_balance, delta, comment) | Correct a store credit balance with a reason. |
All dates are in the store’s timezone as Y-m-d H:i:s.
