Create your first authenticated Donutwork API flow with customers, subscriptions, charges, and webhooks.

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.

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.

Recommended Scopes

Scope	Use
`company:read`	Validate the connected company context.
`customers:write`	Create customers and attach customer subscriptions.
`customers:read`	Read customer records and customer subscription state.
`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 YOUR_API_KEY'

2. Create A Customer

curl --location --request POST \
  'https://api.hub.donutwork.com/2026-02-01/customers.json' \
  --header 'Authorization: Bearer YOUR_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 YOUR_API_KEY'

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

4. Attach A Subscription

curl --location --request POST \
  'https://api.hub.donutwork.com/2026-02-01/customers/CUSTOMER_ID/subscriptions.json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "subscription": {
      "id": "PLAN_PREMIUM_V2",
      "taxes": "TAX_STANDARD_22",
      "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 YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "charge": {
      "capture": true,
      "services": [
        {
          "name": "Technical Consulting",
          "amount": 250.00,
          "taxProfile": "TAX_SERVICES_22"
        }
      ]
    }
  }'

Use charge status and webhook events to reconcile successful, pending, or failed payment outcomes.

6. Register Billing Webhooks

curl --location --request POST \
  'https://api.hub.donutwork.com/2026-02-01/webhooks.json' \
  --header 'Authorization: Bearer YOUR_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": [
        "RecurringPayments.charge.paid",
        "RecurringPayments.charge.failed"
      ]
    }
  }'

For production, use HTTPS endpoints with valid certificates and 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:

API Quickstart

On this page