API Quickstart

Use this quickstart to verify authentication and run the first API flow most SaaS integrations need: create a customer, inspect plans, attach a subscription, create a charge, and subscribe to billing events.

Run these calls from a trusted backend or terminal. Examples use placeholders deliberately; staging and production have separate keys and resource IDs.

Base URL

https://api.hub.donutwork.com/2026-02-01

All requests use Bearer authentication:

Authorization: Bearer YOUR_API_KEY

Keep API keys server-side. Do not expose them in browsers, mobile apps, public repositories, or AI prompt transcripts.

Set an environment variable so the key does not enter shell history:

read -rsp 'Donutwork API key: ' DONUTWORK_API_KEY
export DONUTWORK_API_KEY

Recommended Scopes

Scope	Use
`company:read`	Read the company profile.
`ping:read`	Call the connectivity endpoint.
`customers:write`	Create customers.
`customers:read`	Read customer records.
`customer_subscriptions:write`	Attach a plan to a customer.
`customer_subscriptions:read`	Read customer subscription state.
`taxes:read`	Select tax profiles for subscriptions and charges.
`charges:write`	Create customer charges.
`charges:read`	Reconcile charge status and failed payment state.
`recurring_subscriptions:read`	List available subscription plans.
`webhooks:write`	Register webhook endpoints.
`webhooks:read`	Inspect registered webhooks and supported event types.
`workflow_traces:read`	Review workflow execution traces when recovery or approval flows run.

1. Verify Connectivity

curl --location --request GET \
  'https://api.hub.donutwork.com/2026-02-01/ping.json' \
  --header "Authorization: Bearer $DONUTWORK_API_KEY"

2. Create A Customer

curl --location --request POST \
  'https://api.hub.donutwork.com/2026-02-01/customers.json' \
  --header "Authorization: Bearer $DONUTWORK_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "customer": {
      "company_name": "Acme Corporation",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@acme.example",
      "externalId": "CRM-UID-9921",
      "address": {
        "country": "US",
        "city": "San Francisco",
        "address": "123 Market St"
      }
    }
  }'

Store the returned customer.id. The examples below use CUSTOMER_ID.

3. List Subscription Plans

curl --location --request GET \
  'https://api.hub.donutwork.com/2026-02-01/recurring-payments/subscriptions.json' \
  --header "Authorization: Bearer $DONUTWORK_API_KEY"

Choose the plan id you want to attach to the customer.

List tax profiles with GET /taxes.json and use a tax profile ID from the same company in both the subscription and charge examples. The customer also needs a configured payment method before a captured charge can succeed; without one, the charge request returns 412.

4. Attach A Subscription

curl --location --request POST \
  'https://api.hub.donutwork.com/2026-02-01/customers/CUSTOMER_ID/subscriptions.json' \
  --header "Authorization: Bearer $DONUTWORK_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "subscription": {
      "id": "PLAN_ID",
      "taxes": "TAX_PROFILE_ID",
      "global_discount": {
        "value": 15,
        "type": "percentage"
      }
    }
  }'

5. Create A Charge

curl --location --request POST \
  'https://api.hub.donutwork.com/2026-02-01/customers/CUSTOMER_ID/charges.json' \
  --header "Authorization: Bearer $DONUTWORK_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "charge": {
      "capture": true,
      "services": [
        {
          "name": "Technical Consulting",
          "amount": 250.00,
          "taxProfile": "TAX_PROFILE_ID"
        }
      ]
    }
  }'

Read the charge with GET /customers/CUSTOMER_ID/charges/CHARGE_ID.json and reconcile its current status with webhook events. A successful API response can still report captured: false.

6. Register Billing Webhooks

First call GET /webhooks/types.json to confirm the supported event names for your company. These examples use Charge.succeeded and Charge.failed.

curl --location --request POST \
  'https://api.hub.donutwork.com/2026-02-01/webhooks.json' \
  --header "Authorization: Bearer $DONUTWORK_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "webhook": {
      "name": "Billing Events",
      "description": "Receive charge lifecycle updates",
      "url": "https://example.com/webhooks/donutwork",
      "events": [
        "Charge.succeeded",
        "Charge.failed"
      ]
    }
  }'

Replace the example URL with an HTTPS receiver you control and a valid certificate. Keep the generated webhook token private.

7. Reconcile And Debug

Keep the created customer, subscription, charge, and webhook identifiers in your own logs. When a billing recovery or approval flow runs, use workflow trace access to inspect the operational path.

Recommended next pages:

On this page