SoftSolzSoftSolz
Sign up
HomeAPI GuideAPI ReferenceWidget Tester

Products and Subscriptions

Manage your price list and discount codes, and start subscriptions that bill themselves.

One price list that quotes and invoices read from, plus recurring subscriptions, discount codes and the invoices they produce.

Read the price list

bash
curl https://app.softsolz.uk/api/v1/services/catalog/catalog/products \n  -H "Authorization: Bearer sk_live_your_key"

Fetch one product with GET /catalog/products/{id}, change it with PATCH /catalog/products/{id} and remove it with DELETE /catalog/products/{id}.

Add a product

Prices are whole minor units, so 1200.00 is 120000. The currency code is stored in capitals: send gbp and it is saved and returned as GBP. Fields the API does not know are rejected.

bash
curl -X POST https://app.softsolz.uk/api/v1/services/catalog/catalog/products \n  -H "Authorization: Bearer sk_live_your_key" \n  -H "Content-Type: application/json" \n  -d '{"name":"Annual support","unit_price_cents":120000,"currency":"gbp"}'

Start and manage a subscription

POST /catalog/subscriptions starts a subscription for a customer on a product. Once started it bills itself on each renewal date. Manage it with these actions, each a POST on /catalog/subscriptions/{id}:

  • /pause and /resume stop and restart billing.
  • /cancel ends it now.
  • /cancel-at-period-end keeps it running until the current period ends, then ends it. /undo-cancel reverses that before the period ends.
bash
curl -X POST https://app.softsolz.uk/api/v1/services/catalog/catalog/subscriptions/SUBSCRIPTION_ID/cancel-at-period-end \n  -H "Authorization: Bearer sk_live_your_key"

What each status means

  • trialing: in a free trial, nothing is charged yet.
  • active: running and paid up.
  • past_due: a payment failed and is being retried.
  • paused: billing is stopped until you resume it.
  • canceled: ended. A subscription set to cancel at period end stays active until then.

Discount codes

GET /catalog/coupons lists discount codes with their usage caps and expiry. POST /catalog/coupons creates one. POST /catalog/coupons/{id}/retire stops it being used, and /reactivate turns it back on.

Read invoices

GET /catalog/invoices lists the invoices your subscriptions have produced.

Scopes

Reading needs service.catalog.view and product changes need service.catalog.manage. Starting and managing subscriptions needs service.catalog.subscriptions.manage, and creating or retiring discount codes needs service.catalog.coupons.manage.

Webhook events

The service sends these events. Sign-checking and retries are covered in the webhooks guide.

  • catalog.subscription_started, catalog.subscription_renewed, catalog.subscription_plan_changed
  • catalog.subscription_paused, catalog.subscription_resumed
  • catalog.subscription_cancel_scheduled: a cancel at period end was requested. catalog.subscription_cancel_unscheduled: it was undone.
  • catalog.subscription_canceled, catalog.coupon_redeemed

Next

Full schemas in the API Reference, and the walkthrough on docs.softsolz.uk.