ShopEazydevelopers
API referenceMerchant API BetaBilling

What a plan, add-on, extra, credit pack or the Launch package costs today

Beta
Credentials
  • OAuth access token
Scopes
store:read
Role
Owners and admins only. Staff get 403 forbidden.
GET
/v1/merchant/stores/{storeId}/billing/quote

What the change would charge the saved card today (chargeToday, nothing for a downgrade or a reduction), the next bill where there is one, and whether a card is saved. Refuses what the change itself would refuse, so nobody confirms something that cannot happen. Charges nothing.

Access: OAuth scope store:read; owner/admin only; not write-gated.

Authorization

merchantOAuth store:read
headerAuthorizationBearer <token>

OAuth 2.1 (authorization code + PKCE S256, public clients, dynamic registration) for connected AI apps. Effective power is scopes granted AND the person's role today AND the plan. orders:refund, billing:write and team:write are opt-in on the consent screen. Write implies read for marketing:read and messages:read, so a grant holding marketing:write passes a marketing:read check, and messages:send passes messages:read.

Scope: store:read

Path Parameters

storeId*string

A store the person can reach. Any other id answers 404, never 403.

Query Parameters

change?string

What to quote (required).

Value in"plan""addon""extra""credits""launch"
planId?string

For change=plan.

Value in"starter""growth""scale"
interval?string

For change=plan; the current interval when left out.

Value in"monthly""annual"
addonId?string

For change=addon.

kind?string

For change=extra.

Value in"seats""stores"
quantity?integer

For change=extra: how many extras in all.

Range0 <= value <= 100
packId?string

For change=credits.

Response Body

OK

application/json
  1. response
data*

What a change costs today, from the same sums the charge uses.

Example Request
curl -X GET 'https://api.shopeazy.co/v1/merchant/stores/<storeId>/billing/quote' \  -H 'Authorization: Bearer <access_token>'
Example Response
{  "data": {    "change": "plan",    "cardSaved": false,    "subscribed": false,    "name": "Scale",    "interval": "monthly",    "nextCharge": null,    "upgrade": null,    "held": null,    "credits": null,    "packCredits": null,    "alreadyBooked": null,    "chargeToday": {      "amount": 0,      "currency": "ZAR"    }  }}

Change plan, cancel or resume PATCH

Charges the saved card on an upgrade, and a cancel or resume changes what the shop is billed. `billing:write` is opt-in on the OAuth consent screen. Access: OAuth scope `billing:write`; owner/admin only; write-gated by the subscription.

Switch an add-on on or off PUT

On charges the saved card pro-rata today. Off keeps the add-on working until the renewal that was paid for. Asks nothing: the caller quotes first (`getBillingQuote`) and confirms with the person. `billing:write` is opt-in on the OAuth consent screen. Access: OAuth scope `billing:write`; owner/admin only; write-gated by the subscription.