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"
}

Remove Stored Payment Method

Remove a saved payment method from a customer billing profile. The paymentId path value must be the stored payment record id.

{
  "id": "seti_123",
  "deleted": true
}

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

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...",
  "name": "Starter Monthly",
  "status": "success",
  "next_renew": "2026-04-28",
  "price": {
    "amount": 39,
    "vat": {
      "percentage": 22,
      "name": "VAT Italy"
    }
  },
  "metering": {
    "active": false,
    "balance": {
      "amount": 0,
      "vat": {
        "percentage": 22,
        "name": "VAT Italy"
      }
    }
  },
  "limits": [],
  "addons": [],
  "discount": {
    "value": 0,
    "type": "fixed",
    "until": null
  },
  "lifecycle_status": "active",
  "cancel_at_period_end": false,
  "jobId": "123456"
}

jobId is the processing identifier returned by the platform for the subscription request.
If an identifier cannot be assigned, jobId is returned as false.

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
}

Update Subscription Next Renewal

Move the next renewal boundary for an active customer subscription.

{
  "subscription": {
    "next_renew": "2026-08-01",
    "reason": "Manual billing alignment"
  }
}

{
  "id": "sub_123",
  "status": "success",
  "previous_next_renew": "2026-05-01",
  "next_renew": "2026-08-01"
}

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, Reactivate, 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

Manual renewal retry and expired-subscription reactivation are documented separately below.

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.

Retry a Past-Due Renewal

Queue one immediate manual payment attempt for a subscription that is still past_due and inside its three-day recovery window. The retry keeps the original billing anchor. A successful payment moves the subscription to active; a failure leaves it past_due, or closes it as cancelled when the final recovery day is reached.

Only one manual retry charge can be created for the same subscription, billing cycle, and calendar day. Repeated requests are therefore safe from duplicate charges.

{
  "lifecycle": {}
}

{
  "id": "sub_123",
  "status": "success",
  "lifecycle_status": "past_due",
  "job_id": "123456",
  "queued_at": 1788602400
}

Reactivate an Expired Subscription

Use reactivation for a cancelled subscription or a legacy subscription whose renewal date is older than the three-day recovery window. Reactivation is different from resume: it immediately charges a full new billing period and anchors future renewals to the reactivation day. It never creates automatic retroactive charges for the expired interval.

Each request creates a normal, independently traceable charge. If a payment fails, the subscription remains expired and an operator can submit another reactivation later; that request creates a separate charge. A new request is rejected only while another charge for the same subscription is still pending.

{
  "lifecycle": {}
}

{
  "id": "sub_123",
  "status": "success",
  "lifecycle_status": "active",
  "charge_id": "68c123...",
  "next_renew": "2026-10-20",
  "renewal_recovery": {
    "status": "reactivated",
    "reactivated_on": "2026-09-20"
  }
}

Failed-renewal lifecycle:

• The first failed renewal moves the lifecycle from active to past_due and emits Customer.subscription.past_due once.
• The platform retries once per billing day while preserving the original billing anchor.
• A successful retry returns the lifecycle to active and emits Customer.subscription.recovered.
• The third failed billing day sets both lifecycle and legacy status to cancelled, clears next_renew, and emits Customer.subscription.cancelled.
• If the renewal job misses the final retry day, its next run closes the expired past_due cycle without creating a fourth charge.
• A successful manual reactivation emits Customer.subscription.reactivated.

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"
}