Customers

The Customer API is the central hub for managing your client base. It allows you to synchronize your internal CRM data, manage billing profiles, and monitor subscription health across your organization.

List All Customers

Retrieve a paginated collection of customers associated with your organization. This endpoint is ideal for dashboard overviews and batch synchronization processes.

{
  "entities": "Customer",
  "count": 150,
  "per_page": 100,
  "pages": {
    "current": 1,
    "max": 2
  },
  "elements": [
    {
      "id": "67248941cbe2b1ff8b099a6c",
      "external_id": "CRM-UID-9921",
      "company_name": "Global Logistics S.A.",
      "email": "billing@globallogistics.com"
    }
  ]
}

Technical Implementation

curl --location --request GET \
'https://api.hub.donutwork.com/2026-02-01/customers.json?size=20' \
--header 'Authorization: Bearer YOUR_API_KEY'

const customers = await sdk.customers.list({ size: 20 });
console.table(customers.elements);

Create a New Customer

Initialize a new customer profile. This is the prerequisite step for attaching subscriptions or processing one-time charges. High-quality data at this stage ensures accurate tax calculation and communication delivery.

{
  "customer": {
    "company_name": "Acme Corporation",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@acme.com",
    "externalId": "CRM-UID-9921",
    "address": {
      "country": "US",
      "city": "San Francisco",
      "address": "123 Market St"
    }
  }
}

{
  "customer": {
    "id": "67c9...",
    "partner": null
  }
}

{
  "error": "A customer already exists with this email"
}

Retrieve Customer Details

Fetch the complete profile for a specific customer. This includes organizational metadata, contact information, and summarized subscription status.

{
  "id": "672489...",
  "email": "jane.doe@acme.com",
  "company_name": "Acme Corporation",
  "externalId": "CRM-UID-9921"
}

Search by External Identifier

Locate a customer profile using your internal system's identifier (externalId). This is essential for maintaining synchronization between Donutwork and your primary CRM/ERP.

{
  "id": "672489...",
  "email": "jane.doe@acme.com",
  "externalId": "CRM-UID-9921"
}

{
  "error": "This customer does not exist"
}

Update Customer Profile

Modify an existing customer record. This endpoint supports partial updates (PATCH-style behavior); only the fields included in the request body will be modified. This is useful for updating contact information or adding organizational tags.

{
  "customer": {
    "email": "updated.contact@acme.com",
    "tags": [
      "enterprise",
      "priority-support"
    ]
  }
}

{
  "customer": {
    "id": "6724..."
  }
}

Decommission Customer Profile

Permanently remove a customer profile and all associated metadata. This action is destructive and irreversible. Ensure that all active subscriptions are terminated before choosing to decommission a profile.

{
  "id": "67c9...",
  "deleted": true
}

Customer Properties (Metadata)

Extend the customer profile with custom key-value pairs. Properties are ideal for storing domain-specific data, integration identifiers, or specialized configuration flags that are not captured by standard profile fields.

Retrieve All Properties

Fetch the complete set of custom metadata associated with a customer.

{
  "count": 2,
  "type": "CustomerProperties",
  "elements": {
    "crm_segment": "enterprise",
    "onboarding_status": "completed"
  }
}

Atomic Update/Insert (Upsert) Properties

Update existing property values or append new keys to the customer's property collection. This endpoint performs an "upsert" operation; keys that do not exist will be created, and existing keys will have their values overwritten.

{
  "CustomerProperties": {
    "support_tier": "platinum",
    "preferred_language": "en"
  }
}

{
  "customer": {
    "id": "6724..."
  },
  "CustomerProperties": {
    "support_tier": "platinum",
    "preferred_language": "en"
  }
}

Secure Hosted Payment Link

Generate a unique, short-lived URL for the Donutwork Hosted Payment Page. This secure interface allow customers to update their sensitive payment information (e.g., Credit Card, SEPA Mandate) without sensitive data passing through your servers.

{
  "url": "https://pay.donutwork.com/l/xxxxxxxxxx"
}

Subscription Management

Manage recurring billing cycles and plan associations for your customers. Subscriptions automate the generation of invoices and payment processing based on predefined logic.

List Active and Historical Subscriptions

Retrieve a collection of all subscription entities associated with a customer, including active, canceled, and past-due states.

{
  "type": "CustomerSubscriptions",
  "elements": [
    {
      "id": "sub_123",
      "name": "Enterprise SaaS Plan",
      "status": "success",
      "next_renew": "2026-04-01",
      "price": {
        "amount": 499,
        "vat": {
          "percentage": 22,
          "name": "IVA"
        }
      }
    }
  ]
}

Attach New Subscription

Provision a new subscription for a customer. This endpoint allows for runtime overrides of plan defaults, such as custom discounts and initial addon quantities.

{
  "subscription": {
    "id": "PLAN_PREMIUM_V2",
    "taxes": "TAX_STANDARD_22",
    "global_discount": {
      "value": 15,
      "type": "percentage"
    },
    "addons": [
      {
        "element": "api_quota",
        "quantity": 10000
      }
    ]
  }
}

{
  "id": "sub_67c9...",
  "status": "active"
}

Detach Subscription

Detach a subscription from the customer profile.

{
  "id": "sub_67c9...",
  "deleted": true
}

Retrieve Subscription Status

Read the operational status of a specific customer subscription.

{
  "id": "sub_123",
  "status": "active",
  "next_renew": "2026-05-01"
}

{
  "error": "This subscription does not exists for this customer"
}

Modify Subscription Status

Manually transition a subscription between operational states. This is typically used for administrative overrides or manual churn management.

{
  "subscription": {
    "status": "dismiss"
  }
}

{
  "id": "sub_123",
  "status": "dismiss",
  "next_renew": null
}

Advanced Subscription Lifecycle (Additive)

These endpoints extend subscription lifecycle management without replacing existing legacy routes. Use them when you need pause/resume, plan amendments, scheduled changes, and proration-aware updates.

Read Extended Lifecycle State

{
  "id": "sub_123",
  "status": "success",
  "lifecycle_status": "active",
  "cancel_at_period_end": false,
  "scheduled_change": null,
  "carryover_credit": 0
}

Pause, Resume, Cancel-at-Period-End

{
  "lifecycle": {
    "idempotency_key": "lifecycle-evt-001"
  }
}

{
  "id": "sub_123",
  "lifecycle_status": "paused",
  "amendment": {
    "action": "pause",
    "status": "applied"
  }
}

Use the same payload model with:

• .../lifecycle/resume.json
• .../lifecycle/cancel-at-period-end.json
• .../lifecycle/undo-cancel-at-period-end.json

Pause/resume billing behavior:

• No retroactive automatic billing is created when resuming after a long pause.
• If resumed two months later (for example pause on May 1, 2026 and resume on July 1, 2026), renewal is re-anchored to the resume date (or future resume_at if provided).

Undo-cancel behavior:

• If a subscription is cancel_pending, you can revert it to active before renewal boundary.
• Plan/addons remain the current ones on the subscription; cancellation flag is removed.

Change Plan or Addons with Immediate/Scheduled Application

{
  "lifecycle": {
    "plan_id": "PLAN_ENTERPRISE_V3",
    "taxes": "TAX_STANDARD_22",
    "when": "period_end",
    "proration": true
  }
}

{
  "id": "sub_123",
  "scheduled_change": {
    "type": "plan",
    "apply_on": "2026-06-01"
  },
  "amendment": {
    "action": "change_plan",
    "status": "applied"
  }
}

{
  "lifecycle": {
    "addons": [
      {
        "element": "workspace_seat",
        "quantity": 25
      }
    ],
    "when": "immediate",
    "proration": true
  }
}

{
  "id": "sub_123",
  "carryover_credit": 18.5,
  "amendment": {
    "action": "change_addons",
    "status": "applied"
  }
}

Proration Preview (No Mutation)

{
  "lifecycle": {
    "action": "change_addons",
    "addons": [
      {
        "element": "workspace_seat",
        "quantity": 40
      }
    ]
  }
}

{
  "action": "change_addons",
  "proration": {
    "old_due": 499,
    "new_due": 679,
    "delta": 180,
    "direction": "debit"
  }
}

Amendment History

{
  "type": "CustomerSubscriptionAmendments",
  "elements": [
    {
      "action": "change_addons",
      "when": "immediate",
      "status": "applied"
    }
  ]
}

Backward Compatibility

Lifecycle endpoints are additive and opt-in. Existing integrations can keep using current routes unchanged.

Subscription Addons

Manage the quantity of modular features (addons) attached to a specific subscription. Addons allow for flexible, feature-based pricing.

Audit Addon Quantities

Retrieve a list of all addons currently active on a subscription along with their provisioned quantities.

[
  {
    "element": "compute_units",
    "quantity": 10
  },
  {
    "element": "secondary_domains",
    "quantity": 2
  }
]

Reconcile Addon Quantities

Update the provisioned quantities for one or more addons. This operation is additive or disruptive based on the provided quantity values.

{
  "addons": [
    {
      "element": "compute_units",
      "quantity": 15
    }
  ]
}

{
  "status": "updated"
}

Simulation Interface (Sandbox Only)

Accelerate development cycles by simulating subscription lifecycle events in non-production environments.

Simulate Success Event

Force a successful renewal or provisioning event for a subscription.

{
  "status": "simulated_success"
}

Simulate Failure Event

Force a failed renewal or payment rejection event.

{
  "status": "simulated_failure"
}

Metered Usage Tracking

For subscriptions with metering: true, consumption must be reported via these endpoints. Usage is aggregated and billed at the end of the current billing cycle.

Report Usage Event

Record a new consumption event (e.g., API requests, data processed, seats occupied). Each record requires a unique externalId to prevent idempotent replay errors.

{
  "usage": {
    "amount": 10.5,
    "value": 100,
    "value_type": "api_requests",
    "externalId": "evt_unique_uuid_123"
  }
}

{
  "id": "usage_67c9...",
  "amount": 10.5
}

Audit Usage History

Retrieve a paginated history of all usage events reported for a specific subscription.

{
  "type": "CustomerSubscriptionUsages",
  "elements": []
}

Ad-hoc Charges

Charges represent immediate, non-recurring billable events created independently of a subscription's billing cycle (e.g., setup fees, professional services).

Create One-Time Charge

Generate an ad-hoc charge. If the capture flag is set to true, the system will immediately attempt to authorize and capture the funds using the customer's primary payment method.

{
  "charge": {
    "capture": true,
    "services": [
      {
        "name": "Technical Consulting",
        "amount": 250,
        "taxProfile": "TAX_SERVICES_22"
      }
    ]
  }
}

{
  "status": "success",
  "id": "ch_777",
  "captured": true
}

List Organizational Charges

Retrieve all charges (including pending and failed attempts) associated with a specific customer profile.

{
  "type": "CustomerCharges",
  "elements": []
}

Charge Details and Reconciliation

Retrieve detailed metadata for a specific charge, including its internal lifecycle state and tax calculations.

{
  "id": "ch_777",
  "customer_id": "cust_123",
  "total": 305,
  "type": "one-shot",
  "status": "paid",
  "statuses": {
    "pending": false,
    "paid": true,
    "refunded": false
  },
  "date": {
    "date": "2026-03-01 10:00:00.000000",
    "timezone": "+00:00"
  }
}

External Invoice Synchronization

Manage links to external accounting systems (e.g., Fatture in Cloud) for each charge.

Retrieve Invoice Metadata

{
  "number": "INV-2026-001",
  "date": "2026-03-01",
  "source": "accounting-system",
  "link": "https://docs.acme.com/inv/123.pdf"
}

Persist Invoice Metadata

{
  "invoice": {
    "number": "INV-2026-001",
    "date": "2026-03-01",
    "source": "erp-system",
    "link": "https://erp.example.com/invoices/991.pdf"
  }
}

{
  "status": "success"
}

Global Charge Resolution

Resolve charge details using only the global unique identifier. This is optimized for callback handlers and webhook reconciliation modules.

{
  "id": "ch_777",
  "customer_id": "cust_123"
}