> ## Documentation Index > Fetch the complete documentation index at: https://docs.tolt.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a customer > Creates a customer attributed to a partner. Pass partner_id or link_id, and optionally the click_id that brought them in. ## OpenAPI ````yaml /api-reference/openapi.json post /v2/customers openapi: 3.1.0 info: title: Tolt Public API version: 2.0.0 servers: - url: https://platform.tolt.dev description: Development security: - bearerAuth: [] paths: /v2/customers: post: tags: - Customers summary: Create a customer description: >- Creates a customer attributed to a partner. Pass partner_id or link_id, and optionally the click_id that brought them in. operationId: createCustomer requestBody: required: true content: application/json: schema: type: object properties: email: type: string minLength: 1 maxLength: 255 description: >- Customer's email, stored lowercased and used as their identifier. It must not belong to another customer. Provide this or customer_id. promotion_code: type: string minLength: 1 description: >- Resolve a code in the partner’s program, ignoring case, preferring partner, group, then program scope. An unmatched code leaves attribution unchanged. created_at: type: string format: date-time description: >- When the customer was created, for backdating. Defaults to now; lead_at, and active_at for active customers, default to it. name: type: string maxLength: 255 description: >- Customer's full name as you want it shown in the dashboard; it does not affect attribution or matching. customer_id: type: string minLength: 1 maxLength: 255 description: >- Customer's id in your billing system, such as a Stripe customer id. The billing integration matches payments to this customer by it. Provide this or email. status: type: string enum: - lead - active - canceled - suspended - trialing description: >- Lifecycle stage of the customer. Defaults to lead (signed up, not paying yet); recording a transaction for the customer makes them active. subscription_id: type: string maxLength: 255 description: >- Customer's subscription id in your billing system, such as a Stripe subscription id. click_id: type: string description: >- Id of the tracked click the customer came from, as returned when listing clicks. It must belong to the partner, and its link is used when link_id is omitted. link_id: type: string description: >- Id of the referral link the customer came through (lnk_...). Without partner_id the link's partner is used; with it, the link must belong to that partner. partner_id: type: string description: >- Id of the partner who referred the customer (part_...), as returned when listing partners. The customer joins that partner's program. Provide this or link_id. lead_at: type: - string - 'null' format: date-time description: >- When the customer signed up as a lead, as a timestamp with a time zone, for example 2026-03-01T12:00:00Z. Defaults to created_at. active_at: type: - string - 'null' format: date-time description: >- When the customer became a paying customer, as a timestamp with a time zone. Defaults to created_at when status is active, otherwise it is set when a transaction is recorded for the customer. example: email: alex@example.com name: Alex Morgan customer_id: user_4821 partner_id: part_NLYzgNKuSuASvrvoxNtau6SY link_id: lnk_mtTeeckFa1vMdvDFXretQNs6 description: >- Send at least one of email or customer_id to identify the customer, and at least one of partner_id or link_id to attribute them. A request missing either returns 400. responses: '201': description: The created customer content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Request successful data: $ref: '#/components/schemas/Customer' required: - success - message - data example: success: true message: Successfully created customer data: id: cus_LBfjvtfct9pVUeLojMHiGnXv customer_id: user_4821 identifier: alex@example.com email: alex@example.com name: Alex Morgan status: lead plan: null subscription_id: null partner_id: part_NLYzgNKuSuASvrvoxNtau6SY program_id: prg_T6z8aRW3XCmvFWP972RKxpAd link_id: lnk_mtTeeckFa1vMdvDFXretQNs6 promotion_code_id: null click_id: null lead_at: '2026-10-01T12:00:00Z' active_at: null created_at: '2026-10-01T12:00:00Z' updated_at: '2026-10-01T12:00:00Z' headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false message: 'request: Invalid input: expected object, received null' code: validation_error doc_url: https://docs.tolt.com/errors#validation_error errors: - field: request message: 'Invalid input: expected object, received null' headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false message: Unauthorized code: unauthorized doc_url: https://docs.tolt.com/errors#unauthorized '409': description: Customer email already exists content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false message: Customer with this email already exists code: already_exists doc_url: https://docs.tolt.com/errors#already_exists errors: - field: email message: Customer with this email already exists headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' '413': $ref: '#/components/responses/PayloadTooLarge' '429': $ref: '#/components/responses/RateLimited' components: schemas: Customer: type: object properties: id: type: string example: cus_LBfjvtfct9pVUeLojMHiGnXv customer_id: type: - string - 'null' example: user_4821 identifier: type: - string - 'null' example: alex@example.com email: type: - string - 'null' example: alex@example.com name: type: - string - 'null' example: Alex Morgan status: type: - string - 'null' example: active plan: type: - string - 'null' example: Pro subscription_id: type: - string - 'null' example: sub_R8qW2mN6kP4vT9xY partner_id: type: - string - 'null' example: part_NLYzgNKuSuASvrvoxNtau6SY program_id: type: - string - 'null' example: prg_T6z8aRW3XCmvFWP972RKxpAd link_id: type: - string - 'null' example: lnk_mtTeeckFa1vMdvDFXretQNs6 promotion_code_id: type: - string - 'null' example: promo_gTCAUsWfdmN2GuCVRaHWNRan click_id: type: - string - 'null' example: clk_mEsbFYv6ZjqXjAoFwokjS6v6 lead_at: anyOf: - type: string format: date-time example: '2026-10-01T12:00:00Z' - type: 'null' active_at: anyOf: - type: string format: date-time example: '2026-10-01T12:00:00Z' - type: 'null' created_at: type: string format: date-time example: '2026-10-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-10-01T12:00:00Z' required: - id - customer_id - identifier - email - name - status - plan - subscription_id - partner_id - program_id - link_id - promotion_code_id - click_id - lead_at - active_at - created_at - updated_at Error: type: object properties: success: type: boolean example: false message: type: string description: Human-readable explanation. May change; branch on code instead. code: type: string enum: - bad_request - validation_error - invalid_reference - invalid_cursor - unauthorized - forbidden - not_found - conflict - already_exists - commission_paid - commission_frozen - transaction_refunded - commission_exists - rate_limited - payload_too_large - internal_error description: Stable machine-readable error code. example: not_found doc_url: type: string example: https://docs.tolt.com/errors#not_found errors: type: array items: type: object properties: field: type: string message: type: string required: - field - message description: >- One entry per offending field. Present on validation_error and invalid_reference. required: - success - message - code - doc_url headers: X-RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer X-RateLimit-Remaining: description: Requests left in the current window. schema: type: integer X-RateLimit-Reset: description: Unix time, in seconds, when the window resets. schema: type: integer Retry-After: description: Seconds to wait before retrying. schema: type: integer responses: PayloadTooLarge: description: Request body exceeds 1 MB content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false message: Request body exceeds 1 MB code: payload_too_large doc_url: https://docs.tolt.com/errors#payload_too_large RateLimited: description: The API key exceeded its rate limit headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false message: Too many requests. Retry after the window resets. code: rate_limited doc_url: https://docs.tolt.com/errors#rate_limited securitySchemes: bearerAuth: type: http scheme: bearer description: Tolt API key sent as a bearer token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.