Customer Entity
Understanding the Customer object, its lifecycle, and how it connects to the financial ecosystem.
Customer Entity
The Customer is the central node of the DonutWork ecosystem. It represents the legal entity or individual that consumes your services and generates revenue.
Usage
The Customer entity is used to:
- Track contact and billing information.
- Associate recurring subscriptions and one-time charges.
- Store custom metadata via dynamic properties for deep integration with your own platform.
- Monitor financial risk and health (MRR/YRR).
Expected Implementation Flow
To successfully onboard and bill a customer, follow this standard logical flow:
Customer Lifecycle Initialization
Create the identity using the POST /customers.json endpoint. Assign a unique externalId from your internal database to maintain perfect synchronization.
Context & Property Enrichment
(Optional) Use PUT /customers/{id}/properties.json to store platform-specific data like billing tiers, preferred language, or API quotas.
Secure Payment Onboarding
Call GET /customers/{id}/payment_link.json. This generates a one-time use URL. Redirect your user to this page—DonutWork handles the PCI-compliant credit card entry via Stripe.
Activation & Billing
Once the payment method is attached (confirmed via Webhook), trigger a billing event. You can either attach a Subscription for recurring revenue or create a Charge for one-time fees.
Data Schema
The following table defines the core structure of a Customer object:
| Field | Type | Description |
|---|---|---|
id | eid | Unique extended identifier generated by DonutWork. |
external_id | string | Your internal system identifier. |
email | string | Primary contact and billing email. |
company_name | string | Legal name used for invoicing. |
address | object | Geographic data (country is required for tax logic). |
properties | array | Key-value pairs for custom integration data. |
status | string | active, suspended, or deleted. |
Relationship Call Graph
This graph illustrates how the Customer entity interacts with other core system components during its lifecycle.