{"openapi":"3.1.0","info":{"title":"Usual API","version":"2026-11-07","description":"Every change goes through one audited path. Agent credentials always get a plan first (202), which you apply with POST /plans/{id}/apply."},"servers":[{"url":"http://regular-subs.fly.dev/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Scopes: settings:read, settings:write, audit:read, subscriptions:read, subscriptions:write, subscriptions:sync, offers:read, offers:write, billing:read, billing:write, imports:read, imports:write, integrations:write"}}},"paths":{"/commands":{"get":{"operationId":"listCommands","summary":"List the changes a key can make","description":"Every change this key can make, with its input schema, risk and whether it can be undone.","tags":["Start here"],"x-returns":"{ commands: [{ name, description, risk, reversible, input, http }] }","parameters":[],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/overview":{"get":{"operationId":"getOverview","summary":"See how subscriptions are doing","description":"How the store's subscriptions are doing: whether everything is working, active subscribers, monthly recurring revenue, charges due this week, and setup progress. The best first call.","tags":["Start here"],"x-returns":"{ checks, metrics, trend, forecast, topProducts, activity, setup }","x-scopes":["subscriptions:read"],"parameters":[],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/subscriptions":{"get":{"operationId":"findSubscriptions","summary":"Find subscriptions","description":"Find subscriptions, newest first. Filters combine.","tags":["Subscriptions"],"x-returns":"{ subscriptions: Subscription[], total, nextCursor }","x-scopes":["subscriptions:read"],"parameters":[{"name":"status","in":"query","required":false,"description":"Comma-separated: ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILED.","schema":{"type":"string"}},{"name":"customerId","in":"query","required":false,"description":"A Shopify customer GID.","schema":{"type":"string"}},{"name":"productId","in":"query","required":false,"description":"Has a line for this Shopify product GID.","schema":{"type":"string"}},{"name":"variantId","in":"query","required":false,"description":"Has a line for this Shopify variant GID.","schema":{"type":"string"}},{"name":"sellingPlanId","in":"query","required":false,"description":"Has a line on this selling plan.","schema":{"type":"string"}},{"name":"nextBillingFrom","in":"query","required":false,"description":"Next charge on or after this time (ISO 8601).","schema":{"type":"string"}},{"name":"nextBillingTo","in":"query","required":false,"description":"Next charge on or before this time (ISO 8601).","schema":{"type":"string"}},{"name":"query","in":"query","required":false,"description":"Product title, SKU, or the end of a contract or customer id.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Results per page, 1–100.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/subscriptions/{id}":{"get":{"operationId":"getSubscription","summary":"Look up a subscription","description":"One subscription: its status, lines, prices, schedule, next charge and last payment.","tags":["Subscriptions"],"x-returns":"{ subscription: Subscription }","x-scopes":["subscriptions:read"],"parameters":[{"name":"id","in":"path","required":true,"description":"Our id, or the Shopify contract GID (URL-encoded).","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/subscriptions/{id}/history":{"get":{"operationId":"getSubscriptionHistory","summary":"See a subscription's history","description":"What happened to one subscription, newest first, with who did each thing: the customer, staff, an agent, an API key or Shopify.","tags":["Subscriptions"],"x-returns":"{ subscriptionId, events: [{ at, type, by, to, reason, ... }] }","x-scopes":["subscriptions:read"],"parameters":[{"name":"id","in":"path","required":true,"description":"Our id, or the Shopify contract GID.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/subscriptions/{id}/portal-link":{"get":{"operationId":"getPortalLink","summary":"Get a link for the customer to manage it","description":"A link that opens this subscription in the customer portal on the store's site, or goes straight to cancelling it. Safe to send: the customer logs in first and only ever sees their own subscriptions.","tags":["Subscriptions"],"x-returns":"{ subscriptionId, view, url, note }","x-scopes":["subscriptions:read"],"parameters":[{"name":"id","in":"path","required":true,"description":"Our id, or the Shopify contract GID.","schema":{"type":"string"}},{"name":"view","in":"query","required":false,"description":"manage (default) or cancel.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/subscriptions/{id}/save-offer":{"get":{"operationId":"getSaveOffer","summary":"Get the offer for a customer who wants to cancel","description":"The one offer for a customer who wants to cancel, for their reason (skip, deliver later, less often, pause, swap, or a discount the store allows). Null when there's nothing worth offering. Share it once; if they say no, cancel.","tags":["Cancellation offers"],"x-returns":"{ offer: { kind, heading, detail, accept, ... } | null }","x-scopes":["subscriptions:read"],"parameters":[{"name":"id","in":"path","required":true,"description":"Our id, or the Shopify contract GID.","schema":{"type":"string"}},{"name":"reason","in":"query","required":false,"description":"too_much, too_expensive, taking_break, not_needed, didnt_like or other.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/retention":{"get":{"operationId":"getRetention","summary":"See how cancellation offers are doing","description":"How cancellation offers are doing: customers shown an offer, how many stayed, the save rate and monthly revenue kept, by reason and by offer.","tags":["Cancellation offers"],"x-returns":"{ days, shown, saved, cancelled, saveRate, revenueKept, byOffer, byReason }","x-scopes":["subscriptions:read"],"parameters":[{"name":"days","in":"query","required":false,"description":"How far back to look. Default 30.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/offers":{"get":{"operationId":"listOffers","summary":"List offers","description":"The subscription offers shoppers can choose on product pages: name, frequencies, discount and products.","tags":["Offers"],"x-returns":"{ offers: Offer[] }","x-scopes":["offers:read"],"parameters":[],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}},"post":{"operationId":"offersCreate","summary":"Create an offer","description":"Offer subscriptions on products: a name, one or more delivery frequencies, and an optional discount. Shoppers see it on the product page and choose a frequency at checkout.","tags":["Offers"],"x-command":"offers.create","x-risk":"medium","x-reversible":true,"x-scopes":["offers:write"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"description":"Shown to shoppers, e.g. \"Subscribe & save\""},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"frequencies":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"every":{"type":"integer","minimum":1,"maximum":52},"interval":{"type":"string","enum":["DAY","WEEK","MONTH","YEAR"]}},"required":["every","interval"],"additionalProperties":false},"description":"Delivery options shoppers can choose from"},"discount":{"anyOf":[{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"percentage"},"value":{"type":"number","exclusiveMinimum":0,"exclusiveMaximum":100,"description":"Percent off each order, e.g. 10"}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"fixed_amount"},"amount":{"type":"string","pattern":"^\\d+(\\.\\d{1,3})?$","description":"Amount off each item, in the store's currency"}},"required":["type","amount"],"additionalProperties":false}]},{"type":"null"}],"description":"Applied to every subscription order; null for no discount"},"productIds":{"minItems":1,"maxItems":250,"type":"array","items":{"type":"string","format":"starts_with","pattern":"^gid:\\/\\/shopify\\/Product\\/.*"}}},"required":["name","frequencies","discount","productIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/offers/{id}":{"get":{"operationId":"getOffer","summary":"Look up an offer","description":"One offer.","tags":["Offers"],"x-returns":"{ offer: Offer }","x-scopes":["offers:read"],"parameters":[{"name":"id","in":"path","required":true,"description":"Our id, or the Shopify selling plan group GID.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}},"patch":{"operationId":"offersUpdate","summary":"Change an offer","description":"Change an offer's name, description, delivery frequencies, discount or products. Existing subscriptions keep the terms they started with; changes apply to new subscriptions.","tags":["Offers"],"x-command":"offers.update","x-risk":"medium","x-reversible":true,"x-scopes":["offers:write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1,"maxLength":80},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"frequencies":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"every":{"type":"integer","minimum":1,"maximum":52},"interval":{"type":"string","enum":["DAY","WEEK","MONTH","YEAR"]}},"required":["every","interval"],"additionalProperties":false}},"discount":{"anyOf":[{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"percentage"},"value":{"type":"number","exclusiveMinimum":0,"exclusiveMaximum":100,"description":"Percent off each order, e.g. 10"}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"fixed_amount"},"amount":{"type":"string","pattern":"^\\d+(\\.\\d{1,3})?$","description":"Amount off each item, in the store's currency"}},"required":["type","amount"],"additionalProperties":false}]},{"type":"null"}]},"productIds":{"description":"The full set of products; replaces the current set","minItems":1,"maxItems":250,"type":"array","items":{"type":"string","format":"starts_with","pattern":"^gid:\\/\\/shopify\\/Product\\/.*"}}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}},"delete":{"operationId":"offersDelete","summary":"Stop offering a subscription","description":"Stop offering a subscription option. It disappears from product pages. Existing subscriptions keep running on the terms they started with.","tags":["Offers"],"x-command":"offers.delete","x-risk":"high","x-reversible":false,"x-scopes":["offers:write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/billing/summary":{"get":{"operationId":"getBillingSummary","summary":"See how billing is going","description":"Charges, failed payments, retries and what's due next.","tags":["Billing"],"x-returns":"{ due, retrying, failed, recent, ... }","x-scopes":["billing:read"],"parameters":[],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/billing/cycles":{"get":{"operationId":"listBillingCycles","summary":"List charges and payment attempts","description":"Billing cycles (one per renewal) with their payment attempts, newest first.","tags":["Billing"],"x-returns":"{ cycles: Cycle[], nextCursor }","x-scopes":["billing:read"],"parameters":[{"name":"state","in":"query","required":false,"description":"Comma-separated: scheduled, charging, retry_scheduled, succeeded, exhausted, skipped, cancelled.","schema":{"type":"string"}},{"name":"subscriptionId","in":"query","required":false,"description":"Only this subscription's cycles.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Results per page, 1–100.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/notifications":{"get":{"operationId":"listNotifications","summary":"See which customer emails were sent","description":"Customer emails sent, skipped or failed, newest first, with why. Recipients are masked.","tags":["Customer emails"],"x-returns":"{ notifications: [...], problems: { missingEmailAccess } }","x-scopes":["subscriptions:read"],"parameters":[{"name":"subscriptionId","in":"query","required":false,"description":"Only this subscription's emails.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Results per page, 1–100.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/imports":{"get":{"operationId":"listImports","summary":"List imports","description":"Subscriptions brought in from another app: each upload or fetch, its status and counts.","tags":["Imports"],"x-returns":"{ imports: Import[] }","x-scopes":["imports:read"],"parameters":[],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}},"post":{"operationId":"importsCreate","summary":"Upload subscriptions to import","description":"Upload a subscriptions export from another app (Recharge, Skio, Appstle, Loop, Seal, Shopify Subscriptions or a spreadsheet). Nothing is created yet: each subscription is checked against the store (customer, saved card, products, date) in the background. Read the import to see what's ready and what needs fixing, then run imports.start.","tags":["Imports"],"x-command":"imports.create","x-risk":"low","x-reversible":false,"x-scopes":["imports:write"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"csv":{"type":"string","minLength":1,"description":"The export from the other app, as CSV text, header row first"},"filename":{"type":"string","maxLength":200},"source":{"description":"Which app it came from. Guessed from the columns when left out.","type":"string","enum":["recharge","skio","appstle","loop","seal","shopify","other"]}},"required":["csv"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/imports/{id}":{"get":{"operationId":"getImport","summary":"Check an import","description":"One import: problems grouped by kind with examples, warnings, a preview of what will be created, failures, and how many are waiting to bill.","tags":["Imports"],"x-returns":"{ import: ImportDetail }","x-scopes":["imports:read"],"parameters":[{"name":"id","in":"path","required":true,"description":"The import's id.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/plans":{"post":{"operationId":"createPlan","summary":"Preview a change","description":"Preview any command without applying it. Returns exactly what would change and whether it needs a person's approval.","tags":["Plans and activity"],"x-returns":"{ status: \"planned\", plan: Plan }","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["command","input"],"properties":{"command":{"type":"string","description":"A command name from GET /commands"},"input":{"type":"object","description":"The command's input"},"reason":{"type":"string","description":"Why; required for agents"}}}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/plans/{id}":{"get":{"operationId":"getPlan","summary":"Check a preview","description":"A plan: its preview, status (pending, awaiting_approval, applied, rejected, stale, expired) and what to do next.","tags":["Plans and activity"],"x-returns":"{ plan: Plan }","parameters":[{"name":"id","in":"path","required":true,"description":"The plan's id.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/plans/{id}/apply":{"post":{"operationId":"applyPlan","summary":"Apply a preview","description":"Apply a plan exactly as previewed. Refused if anything changed since it was made.","tags":["Plans and activity"],"x-returns":"{ status: \"applied\", auditId, diff, result } or { status: \"planned\" } while it waits for approval","parameters":[{"name":"id","in":"path","required":true,"description":"The plan's id.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/activity":{"get":{"operationId":"listActivity","summary":"See every change","description":"Every change ever applied, newest first: what, who, why, and whether it can be undone.","tags":["Plans and activity"],"x-returns":"{ activity: [...], nextCursor }","x-scopes":["audit:read"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Results per page, 1–100.","schema":{"type":"integer"}},{"name":"before","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/activity/{id}/undo":{"post":{"operationId":"undoChange","summary":"Undo a change","description":"Reverse a change by running its recorded inverse as a new change. Agents get a plan to apply.","tags":["Plans and activity"],"x-returns":"Same as any change: applied, or a plan","parameters":[{"name":"id","in":"path","required":true,"description":"The activity entry's id.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/settings":{"get":{"operationId":"getSettings","summary":"Read store settings","description":"Store settings: sender name, support email, retry schedule, customer emails, cancellation offers.","tags":["Store"],"x-returns":"{ settings: Settings }","x-scopes":["settings:read"],"parameters":[],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}},"patch":{"operationId":"shopUpdateSettings","summary":"Change store settings","description":"Change store-wide subscription settings: sender name, support email, the failed-payment retry schedule, what happens after the final retry, and which customer emails are sent. Only the fields you pass change.","tags":["Store"],"x-command":"shop.update_settings","x-risk":"medium","x-reversible":true,"x-scopes":["settings:write"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"senderName":{"type":"string","minLength":1,"maxLength":80,"description":"Name shown on subscriber emails and texts."},"supportEmail":{"anyOf":[{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}],"description":"Where subscriber replies go. null to use the store's contact email."},"accountPageUrl":{"anyOf":[{"type":"string","maxLength":500,"format":"uri"},{"type":"null"}],"description":"The store's Subscriptions page in customer accounts, copied from the checkout and accounts editor. Customer emails and links go there. null to use the customer account home."},"dunningRetryDays":{"minItems":1,"maxItems":6,"type":"array","items":{"type":"integer","minimum":1,"maximum":30},"description":"Days after a failed charge to retry it, in order."},"afterFinalRetry":{"type":"string","enum":["pause","cancel"],"description":"What happens to a subscription when every retry has failed."},"billingPaused":{"type":"boolean","description":"Stop all new charges for this store. Charges already sent still finish."},"notices":{"type":"object","properties":{"confirmation":{"type":"boolean","description":"Email subscribers their terms and how to cancel when they sign up."},"upcomingCharge":{"type":"boolean","description":"Remind subscribers before each renewal charge."},"upcomingChargeDays":{"type":"integer","minimum":1,"maximum":14,"description":"How many days before a charge to remind them."},"paymentFailed":{"type":"boolean","description":"Tell subscribers when a renewal payment fails."},"cancelled":{"type":"boolean","description":"Confirm cancellations by email."}},"required":["confirmation","upcomingCharge","upcomingChargeDays","paymentFailed","cancelled"],"description":"Which customer emails Usual sends. Turn off any you'd rather send yourself."},"retention":{"type":"object","properties":{"offers":{"type":"object","properties":{"skip":{"type":"boolean","description":"Skip the next delivery instead."},"later":{"type":"boolean","description":"Get the next delivery two weeks later."},"lessOften":{"type":"boolean","description":"Switch to a less frequent schedule from the subscription's offer."},"pause":{"type":"boolean","description":"Pause until they resume."},"swap":{"type":"boolean","description":"Swap to another option of the same product."},"discount":{"type":"boolean","description":"A discount on the next few deliveries."}},"required":["skip","later","lessOften","pause","swap","discount"],"description":"Which offers customers can see when they cancel. One fits their reason; cancelling stays one click."},"discountPercent":{"type":"integer","minimum":5,"maximum":50,"description":"The discount, in percent."},"discountDeliveries":{"type":"integer","minimum":1,"maximum":6,"description":"How many deliveries the discount lasts."}},"required":["offers","discountPercent","discountDeliveries"],"description":"What customers are offered when they go to cancel."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/sync-runs":{"get":{"operationId":"getSyncStatus","summary":"Check the last re-sync with Shopify","description":"Recent re-checks of our data against Shopify: when, how many were checked, and how many were out of date.","tags":["Store"],"x-returns":"{ runs: [...] }","x-scopes":["subscriptions:read"],"parameters":[],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/subscriptions/reconcile":{"post":{"operationId":"subscriptionsReconcile","summary":"Re-check subscriptions against Shopify","description":"Re-check every subscription against Shopify and fix anything out of date. Runs in the background; check progress with get_sync_status. Safe to run any time: it only reads from Shopify and updates our copy.","tags":["Subscriptions"],"x-command":"subscriptions.reconcile","x-risk":"low","x-reversible":false,"x-scopes":["subscriptions:sync"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/subscriptions/{subscriptionId}/skip":{"post":{"operationId":"subscriptionsSkipNext","summary":"Skip the next delivery","description":"Skip the next delivery. The next charge moves on by one delivery interval (e.g. a month). Good for customers with too much product who'd otherwise cancel.","tags":["Subscriptions"],"x-command":"subscriptions.skip_next","x-risk":"low","x-reversible":true,"x-scopes":["subscriptions:write"],"parameters":[{"name":"subscriptionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"subscriptionId":{"type":"string","minLength":1,"description":"Our subscription id, or the Shopify contract GID"}},"required":["subscriptionId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/subscriptions/{subscriptionId}/reschedule":{"post":{"operationId":"subscriptionsReschedule","summary":"Move the next delivery","description":"Move the next delivery to a specific date (tomorrow to a year out). Later deliveries follow on from the new date at the usual interval.","tags":["Subscriptions"],"x-command":"subscriptions.reschedule","x-risk":"low","x-reversible":true,"x-scopes":["subscriptions:write"],"parameters":[{"name":"subscriptionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"subscriptionId":{"type":"string","minLength":1,"description":"Our subscription id, or the Shopify contract GID"},"date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"New next delivery date, YYYY-MM-DD in the store's timezone"}},"required":["subscriptionId","date"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/subscriptions/{subscriptionId}/pause":{"post":{"operationId":"subscriptionsPause","summary":"Pause a subscription","description":"Pause a subscription: no charges or deliveries until it's resumed.","tags":["Subscriptions"],"x-command":"subscriptions.pause","x-risk":"medium","x-reversible":true,"x-scopes":["subscriptions:write"],"parameters":[{"name":"subscriptionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"subscriptionId":{"type":"string","minLength":1,"description":"Our subscription id, or the Shopify contract GID"}},"required":["subscriptionId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/subscriptions/{subscriptionId}/resume":{"post":{"operationId":"subscriptionsResume","summary":"Resume a subscription","description":"Resume a paused subscription. If its next delivery date has passed, the next delivery is tomorrow at the usual time.","tags":["Subscriptions"],"x-command":"subscriptions.resume","x-risk":"low","x-reversible":true,"x-scopes":["subscriptions:write"],"parameters":[{"name":"subscriptionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"subscriptionId":{"type":"string","minLength":1,"description":"Our subscription id, or the Shopify contract GID"}},"required":["subscriptionId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/subscriptions/{subscriptionId}/cancel":{"post":{"operationId":"subscriptionsCancel","summary":"Cancel a subscription","description":"Cancel a subscription. No more charges or deliveries. Record why: it drives which save offers are worth making. Customers can always cancel in one step.","tags":["Subscriptions"],"x-command":"subscriptions.cancel","x-risk":"high","x-reversible":false,"x-scopes":["subscriptions:write"],"parameters":[{"name":"subscriptionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"subscriptionId":{"type":"string","minLength":1,"description":"Our subscription id, or the Shopify contract GID"},"reason":{"type":"string","enum":["too_much","too_expensive","taking_break","not_needed","didnt_like","other"]},"comment":{"type":"string","maxLength":500}},"required":["subscriptionId","reason"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/subscriptions/{subscriptionId}/save":{"post":{"operationId":"subscriptionsAcceptSaveOffer","summary":"Keep a customer with an offer","description":"Take the offer shown to a customer who was about to cancel (skip, deliver later, less often, pause, swap, or a discount) instead of cancelling. Get the offer first with get_save_offer for the customer's reason; only that offer can be accepted. Recorded as a save in the retention report.","tags":["Cancellation offers"],"x-command":"subscriptions.accept_save_offer","x-risk":"medium","x-reversible":false,"x-scopes":["subscriptions:write"],"parameters":[{"name":"subscriptionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"subscriptionId":{"type":"string","minLength":1,"description":"Our subscription id, or the Shopify contract GID"},"reason":{"type":"string","enum":["too_much","too_expensive","taking_break","not_needed","didnt_like","other"]},"offer":{"type":"string","enum":["skip","later","less_often","pause","swap","discount"],"description":"The offer's kind, from get_save_offer"},"variantId":{"description":"For swap: the variant chosen","type":"string","format":"starts_with","pattern":"^gid:\\/\\/shopify\\/ProductVariant\\/.*"}},"required":["subscriptionId","reason","offer"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/subscriptions/{subscriptionId}/payment-update":{"post":{"operationId":"subscriptionsSendPaymentUpdate","summary":"Email a card update link","description":"Email the customer a secure Shopify link to update the card on this subscription. Use it after a declined or expired card, or when a customer asks. At most once an hour per subscription.","tags":["Billing"],"x-command":"subscriptions.send_payment_update","x-risk":"low","x-reversible":false,"x-scopes":["subscriptions:write"],"parameters":[{"name":"subscriptionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"subscriptionId":{"type":"string","minLength":1,"description":"Our subscription id, or the Shopify contract GID"}},"required":["subscriptionId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/subscriptions/{subscriptionId}/quantity":{"post":{"operationId":"subscriptionsChangeQuantity","summary":"Change a quantity","description":"Change how many of an item come in each delivery. The price per item stays the same; the charge changes with the quantity.","tags":["Subscriptions"],"x-command":"subscriptions.change_quantity","x-risk":"low","x-reversible":true,"x-scopes":["subscriptions:write"],"parameters":[{"name":"subscriptionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"subscriptionId":{"type":"string","minLength":1,"description":"Our subscription id, or the Shopify contract GID"},"lineId":{"description":"Which line (our line id or the Shopify line GID). Optional when there's only one.","type":"string","minLength":1},"quantity":{"type":"integer","minimum":1,"maximum":99,"description":"How many of this item in each delivery"}},"required":["subscriptionId","quantity"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/subscriptions/{subscriptionId}/frequency":{"post":{"operationId":"subscriptionsChangeFrequency","summary":"Change how often it delivers","description":"Change how often deliveries come, to another frequency on the same offer (e.g. every 4 weeks instead of every 2). The next charge date stays; later ones follow the new frequency.","tags":["Subscriptions"],"x-command":"subscriptions.change_frequency","x-risk":"low","x-reversible":true,"x-scopes":["subscriptions:write"],"parameters":[{"name":"subscriptionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"subscriptionId":{"type":"string","minLength":1,"description":"Our subscription id, or the Shopify contract GID"},"every":{"type":"integer","minimum":1,"maximum":52,"description":"Deliver every N intervals"},"interval":{"type":"string","enum":["DAY","WEEK","MONTH","YEAR"]}},"required":["subscriptionId","every","interval"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/subscriptions/{subscriptionId}/variant":{"post":{"operationId":"subscriptionsSwapVariant","summary":"Swap to another variant","description":"Switch an item to another variant of the same product (size, flavour, grind). The subscription discount carries over to the new variant's price.","tags":["Subscriptions"],"x-command":"subscriptions.swap_variant","x-risk":"low","x-reversible":true,"x-scopes":["subscriptions:write"],"parameters":[{"name":"subscriptionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"subscriptionId":{"type":"string","minLength":1,"description":"Our subscription id, or the Shopify contract GID"},"lineId":{"description":"Which line (our line id or the Shopify line GID). Optional when there's only one.","type":"string","minLength":1},"variantId":{"type":"string","format":"starts_with","pattern":"^gid:\\/\\/shopify\\/ProductVariant\\/.*","description":"Another variant of the same product"}},"required":["subscriptionId","variantId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/subscriptions/{subscriptionId}/address":{"post":{"operationId":"subscriptionsChangeAddress","summary":"Change the shipping address","description":"Ship future deliveries to a new address. The shipping price and method stay as they are, and Shopify refuses an address the store doesn't ship to. The address isn't kept in the activity log.","tags":["Subscriptions"],"x-command":"subscriptions.change_address","x-risk":"low","x-reversible":false,"x-scopes":["subscriptions:write"],"parameters":[{"name":"subscriptionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"subscriptionId":{"type":"string","minLength":1,"description":"Our subscription id, or the Shopify contract GID"},"address":{"type":"object","properties":{"firstName":{"type":"string","maxLength":100},"lastName":{"type":"string","maxLength":100},"company":{"type":"string","maxLength":100},"address1":{"type":"string","minLength":1,"maxLength":200},"address2":{"type":"string","maxLength":200},"city":{"type":"string","minLength":1,"maxLength":100},"provinceCode":{"description":"Province or state code, e.g. ON or CA","type":"string","maxLength":10},"countryCode":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Two-letter country code, e.g. CA"},"zip":{"type":"string","maxLength":20},"phone":{"type":"string","maxLength":30}},"required":["address1","city","countryCode"],"additionalProperties":false,"description":"Where future deliveries should go"}},"required":["subscriptionId","address"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/billing/cycles/{cycleId}/retry":{"post":{"operationId":"billingRetryNow","summary":"Retry a failed payment now","description":"Retry a failed charge now instead of waiting for the next scheduled retry, e.g. after the customer says they've updated their card. Charges the customer's payment method.","tags":["Billing"],"x-command":"billing.retry_now","x-risk":"financial","x-reversible":false,"x-scopes":["billing:write"],"parameters":[{"name":"cycleId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"cycleId":{"type":"string","minLength":1}},"required":["cycleId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/imports/{importId}/start":{"post":{"operationId":"importsStart","summary":"Create the imported subscriptions","description":"Create the import's ready subscriptions in Shopify, keeping each one's next charge date, price and schedule. They're created in the background, one at a time. They don't bill until imports.release_billing, so the old app has time to be switched off. Subscriptions with problems are left out.","tags":["Imports"],"x-command":"imports.start","x-risk":"medium","x-reversible":false,"x-scopes":["imports:write"],"parameters":[{"name":"importId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"importId":{"type":"string","minLength":1,"description":"The import's id, from imports.create"},"limit":{"description":"Import only this many (e.g. 10) to check them in Shopify first. The rest stay ready.","type":"integer","minimum":1,"maximum":100000}},"required":["importId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/imports/{importId}/release-billing":{"post":{"operationId":"importsReleaseBilling","summary":"Start billing imported subscriptions","description":"Start billing an import's subscriptions here. Run it only once the old app has stopped charging them (turned off or uninstalled), or customers will be charged twice. Any whose charge date passed while waiting move to their next date, since the old app charged them.","tags":["Imports"],"x-command":"imports.release_billing","x-risk":"high","x-reversible":false,"x-scopes":["imports:write"],"parameters":[{"name":"importId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"importId":{"type":"string","minLength":1,"description":"The import's id, from imports.create"}},"required":["importId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/imports/{importId}":{"delete":{"operationId":"importsDiscard","summary":"Throw away an import","description":"Throw away an import that hasn't created anything yet, e.g. to upload a corrected file. Imports that have created subscriptions can't be discarded.","tags":["Imports"],"x-command":"imports.discard","x-risk":"low","x-reversible":false,"x-scopes":["imports:write"],"parameters":[{"name":"importId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"importId":{"type":"string","minLength":1,"description":"The import's id, from imports.create"}},"required":["importId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/imports/connections":{"post":{"operationId":"importsConnect","summary":"Connect Recharge","description":"Connect the app the store is moving from with an API token from it, so subscriptions (and cards held at Stripe, Braintree or Authorize.net) can be fetched directly, and cancelled there when billing switches over. For Recharge the token needs: read_subscriptions, read_customers, read_payment_methods, write_subscriptions. The token is stored encrypted and never shown again.","tags":["Imports"],"x-command":"imports.connect","x-risk":"medium","x-reversible":false,"x-scopes":["imports:write"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"source":{"type":"string","enum":["recharge"],"description":"The app to connect. Recharge for now."},"token":{"type":"string","minLength":10,"maxLength":500,"description":"An API token created in that app"}},"required":["source","token"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/imports/connections/{source}":{"delete":{"operationId":"importsDisconnect","summary":"Disconnect Recharge","description":"Remove the stored API token for the app the store moved from. Delete the token in that app too.","tags":["Imports"],"x-command":"imports.disconnect","x-risk":"low","x-reversible":false,"x-scopes":["imports:write"],"parameters":[{"name":"source","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"source":{"type":"string","enum":["recharge"]}},"required":["source"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/imports/connections/{source}/fetch":{"post":{"operationId":"importsFetch","summary":"Fetch subscriptions from Recharge","description":"Fetch every active subscription from the connected app (Recharge) and check them against the store, like an upload but always current. Nothing is created yet. Read the import, then run imports.start.","tags":["Imports"],"x-command":"imports.fetch","x-risk":"low","x-reversible":false,"x-scopes":["imports:write"],"parameters":[{"name":"source","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"source":{"type":"string","enum":["recharge"]}},"required":["source"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}},"/integrations/klaviyo":{"post":{"operationId":"integrationsConnectKlaviyo","summary":"Connect Klaviyo","description":"Send subscription events (started, cancelled, upcoming charge, order placed, payment failed...) to the store's Klaviyo account, for its own flows. The private API key needs: Accounts: Read, Events: Full, Profiles: Full.","tags":["Store"],"x-command":"integrations.connect_klaviyo","x-risk":"medium","x-reversible":false,"x-scopes":["integrations:write"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"apiKey":{"type":"string","minLength":10,"maxLength":200,"description":"A Klaviyo private API key (pk_...)"}},"required":["apiKey"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}},"delete":{"operationId":"integrationsDisconnectKlaviyo","summary":"Disconnect Klaviyo","description":"Stop sending subscription events to Klaviyo and remove the stored key.","tags":["Store"],"x-command":"integrations.disconnect_klaviyo","x-risk":"low","x-reversible":false,"x-scopes":["integrations:write"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original response instead of repeating the change.","schema":{"type":"string","maxLength":255}},{"name":"preview","in":"query","schema":{"type":"boolean"},"description":"Return a plan instead of applying"},{"name":"X-Change-Reason","in":"header","schema":{"type":"string"},"description":"Why; required for agents"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Applied, or nothing to change (status: applied | noop)"},"202":{"description":"Previewed or waiting for approval (status: planned)"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Not allowed (scope or policy)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Plan isn't applicable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}}}}}}}}}}}}}