createCustomer

Mock

Mock. This operation is part of the approved contract but its module is not built yet. Run Core with N1_API_MODE=mock N1_DEV_AUTH=stub to get deterministic demo-shop data from it. The real server answers NOT_IMPLEMENTED until it ships; the schema and examples here will not change when it does.

Add a customer

Compare

Add a customer. Owner, admin and accountant.

POST/graphqlapp audience

Who can call this. Owner, admin and accountant. You can run it against Local or Staging from the request panel, with a demo-shop token.

Headers

Required Optional

AuthorizationstringRequired
Bearer <token>, issued for this endpoint's audience. The token decides the shop and roles; nothing in the request body can change them.
Example: Bearer eyJhbGciOiJFZERTQSJ9…
Content-TypestringRequired
Always application/json. Only POST is accepted.
Example: application/json
Idempotency-KeystringRequired
A key you generate once per user action (a UUID). Retrying with the same key never applies the change twice.
Example: 0192f0c1-9b2a-7d40-8c3e-1f5a6b7c8d9e
X-Request-IdstringOptional
Your id for this request (8–128 characters of A–Z a–z 0–9 . _ : -). Echoed back in the response header and in every error, so you can quote it when reporting a problem. Core makes one if you send none.
Example: app-7f3c2a9e-checkout

Arguments

Required Optional

inputCustomerInput!Required
The customer.
Example: {"name":"Zenith Gears Demo","gstin":"27DEMOZ0001A1Z5","phone":"+91 98000 99001","email":"purchase@zenith-demo.example","paymentTermsDays":30,"billingAddress":{"line1":"7 Demo Mill Road","line2":null,"city":"Pune","state":"Maharashtra","pincode":"411001"},"contacts":[{"name":"Meera Demo","designation":"Purchase manager","phone":"+91 98000 99002","email":"meera@zenith-demo.example"}]}
Show children
- billingAddressAddressInput!Required
  Where invoices go.
- contacts[CustomerContactInput!]Optional
  People at the customer, at most 20.
- emailStringOptional
  Main email.
- gstinStringOptional
  GSTIN, if registered.
- nameString!Required
  Company name.
- paymentTermsDaysInt!Required
  Days after the invoice date that payment is due, 0–365.
- phoneStringOptional
  Main phone.
- shippingAddressAddressInputOptional
  Where parts go, when different from billing.
- statusCustomerStatusOptional
  Default ACTIVE.

Returns

Required Optional

createCustomerCustomer!Required
Add a customer. Owner, admin and accountant.
Show children
- billingAddressAddress!Required
  Where invoices go.
  Example: {"city":"Pune","state":"Maharashtra"}
  Show children
  - cityString!Required
    City or town.
    Example: "Pune"
  - line1String!Required
    Building, street.
  - line2StringOptional
    Area, landmark.
  - pincodeString!Required
    6-digit PIN code.
  - stateString!Required
    State name.
    Example: "Maharashtra"
- contacts[CustomerContact!]!Required
  People at the customer, at most 20.
  Example: [{"id":"0192f0c1-0000-7000-8000-d00000001001","name":"Meera Demo","phone":"+91 98000 99002"}]
  Show children
  - designationStringOptional
    Job title.
  - emailStringOptional
    Email address.
  - idID!Required
    Stable id (UUIDv7).
    Example: "0192f0c1-0000-7000-8000-d00000001001"
  - nameString!Required
    Full name.
    Example: "Meera Demo"
  - phoneStringOptional
    Phone number.
    Example: "+91 98000 99002"
- createdAtString!Required
  UTC time the customer was added.
- emailStringOptional
  Main email.
- gstinStringOptional
  GSTIN, if registered.
  Example: "27DEMOZ0001A1Z5"
- idID!Required
  Stable id (UUIDv7).
  Example: "0192f0c1-0000-7000-8000-c00000001000"
- nameString!Required
  Company name.
  Example: "Zenith Gears Demo"
- paymentTermsDaysInt!Required
  Days after the invoice date that payment is due; 0 = on delivery.
  Example: 30
- phoneStringOptional
  Main phone.
  Example: "+91 98000 99001"
- shippingAddressAddressOptional
  Where parts go, when different from billing.
  Show children
  - cityString!Required
    City or town.
  - line1String!Required
    Building, street.
  - line2StringOptional
    Area, landmark.
  - pincodeString!Required
    6-digit PIN code.
  - stateString!Required
    State name.
- statusCustomerStatus!Required
  Whether new orders can be taken.
  Example: "ACTIVE"
  - ACTIVEOrders can be taken.
  - INACTIVEKept for history; hidden from pickers. Use this instead of deleting a customer who has orders.
- updatedAtString!Required
  UTC time of the last change.

Errors

Code	HTTP	When
`VALIDATION_FAILED`	`400`	Input failed Zod or route schema validation. `details` lists each field path and problem.
`FORBIDDEN`	`403`	Signed in, but the role or tenant does not allow the action.

Every error has the same body. See Errors.

Rate limit tier

Tier: per user. Over the limit you get RATE_LIMITED (HTTP 429) with a Retry-After header. See Response handling.