App billing

Get your app’s billing on this shopCopy Anchor Link

GET /api/v1/app-billing

The plan in force, this period’s usage, a cheaper plan waiting to start, the charges waiting for the merchant, the one-time charges approved among your last 50, and the plans your installed release declares, priced in the shop’s currency.

Answers only your app’s own token for the shop, and needs no permission.

Answers 200

curl "https://api.storeware.ai/api/v1/app-billing" \
  -H "Authorization: Bearer $TOKEN"

Ask the merchant to approve a planCopy Anchor Link

POST /api/v1/app-billing/subscriptions

Asks for one of the plans your installed release declares. Send the merchant to confirmationUrl: nothing is charged until they approve, and they have 48 hours to. returnUrl must be https on your app’s own address (its app.url, webhook URL or a redirect URI). Asking for the plan already in force answers with it and changes nothing. At most 5 charges may wait for an answer at once. Send the same idempotencyKey again and you are answered with the first result, so a retry never charges twice.

Answers only your app’s own token for the shop, and needs no permission.

Body

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/app-billing/subscriptions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

End your plan on this shopCopy Anchor Link

POST /api/v1/app-billing/subscriptions/{subscriptionId}/cancel

Ends the plan when the period the merchant has paid for ends. Until then it stays in force.

Answers only your app’s own token for the shop, and needs no permission.

Parameters

Answers 200

curl -X POST "https://api.storeware.ai/api/v1/app-billing/subscriptions/$SUBSCRIPTION_ID/cancel" \
  -H "Authorization: Bearer $TOKEN"

Ask the merchant to approve a one-time chargeCopy Anchor Link

POST /api/v1/app-billing/purchases

Give a price in every currency: the shop is charged in its own, and nothing is converted. Send the merchant to confirmationUrl; nothing is charged until they approve, and they have 48 hours to. returnUrl follows the same rule as for a plan. Send the same idempotencyKey again and you are answered with the first result, so a retry never charges twice.

Answers only your app’s own token for the shop, and needs no permission.

Body

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/app-billing/purchases" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Report what the shop usedCopy Anchor Link

POST /api/v1/app-billing/usage

Adds to this period’s usage, in the plan’s currency, on a plan that charges by use. It is billed when the period ends. Past the period’s cap it is refused with 402 app_usage_cap_reached, and on a plan with no usage with 409. Send the same idempotencyKey again and you are answered with the first result, so a retry never charges twice.

Answers only your app’s own token for the shop, and needs no permission.

Body

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/app-billing/usage" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Credit the shopCopy Anchor Link

POST /api/v1/app-billing/credits

Takes an amount off the shop’s next statement, in its billing currency. A credit can come to no more than the shop paid your app in the last year, less what it has already been credited; past that it is refused with 409. Send the same idempotencyKey again and you are answered with the first result, so a retry never charges twice.

Answers only your app’s own token for the shop, and needs no permission.

Body

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/app-billing/credits" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json