customers

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.

The shop’s customers, paged and searchable

Compare

The shop’s customers, paged. Search matches name, GSTIN and phone.

POST/graphqlapp audience

Who can call this. Owner, admin, accountant and supervisor. 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
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

afterStringOptional
endCursor of the previous page.
beforeStringOptional
startCursor of the next page, when paging backwards.
filterCustomerFilterOptional
Narrow by status or city.
Show children
- cityStringOptional
  Only customers billed in this city (not case-sensitive).
- statusCustomerStatusOptional
  Only active or only inactive customers.
firstIntOptional
Page size, 1–100 (default 20).
Example: 3
lastIntOptional
Page size when paging backwards, 1–100.
searchStringOptional
Free text, 1–100 characters.
sortCustomerSortOptional
Order (default: name, A to Z).
Show children
- directionSortDirection!Required
  Ascending or descending.
- fieldCustomerSortField!Required
  What to order by.

Returns

Required Optional

customersCustomerConnection!Required
The shop’s customers, paged. Search matches name, GSTIN and phone.
Show children
- edges[CustomerEdge!]!Required
  The rows on this page, in order.
  Example: [{"cursor":"WyJhbHBoYSBhdXRvIGNvbXBvbmVudHMgMSIsIjAxOTJmMGMxLTAwMDAtNzAwMC04MDAwLTAwMDAwMDBjMDAwMSJd","node":{"id":"0192f0c1-0000-7000-8000-0000000c0001","name":"Alpha Auto Components 1","gstin":"33DEMOA0001A1Z5","phone":"+91 98000 10001","status":"ACTIVE","billingAddress":{"city":"Coimbatore"}}},{"cursor":"WyJhbHBoYSBhdXRvIGNvbXBvbmVudHMgMTkiLCIwMTkyZjBjMS0wMDAwLTcwMDAtODAwMC0wMDAwMDAwYzAwMTMiXQ","node":{"id":"0192f0c1-0000-7000-8000-0000000c0013","name":"Alpha Auto Components 19","gstin":"33DEMOD0019A1Z5","phone":"+91 98000 10019","status":"ACTIVE","billingAddress":{"city":"Chennai"}}},{"cursor":"WyJhbHBoYSBhdXRvIGNvbXBvbmVudHMgMzciLCIwMTkyZjBjMS0wMDAwLTcwMDAtODAwMC0wMDAwMDAwYzAwMjUiXQ","node":{"id":"0192f0c1-0000-7000-8000-0000000c0025","name":"Alpha Auto Components 37","gstin":"33DEMOB0037A1Z5","phone":"+91 98000 10037","status":"ACTIVE","billingAddress":{"city":"Pune"}}}]
  Show children
  - cursorString!Required
    Opaque position of this row in the list.
    Example: "WyJhbHBoYSBhdXRvIGNvbXBvbmVudHMgMSIsIjAxOTJmMGMxLTAwMDAtNzAwMC04MDAwLTAwMDAwMDBjMDAwMSJd"
  - nodeCustomer!Required
    The Customer.
    Example: {"id":"0192f0c1-0000-7000-8000-0000000c0001","name":"Alpha Auto Components 1","gstin":"33DEMOA0001A1Z5","phone":"+91 98000 10001","status":"ACTIVE","billingAddress":{"city":"Coimbatore"}}
    Show children
    billingAddressAddress!Required
    Where invoices go.
    Example: {"city":"Coimbatore"}
    Show children
    cityString!Required
    City or town.
    Example: "Coimbatore"
    line1String!Required
    Building, street.
    line2StringOptional
    Area, landmark.
    pincodeString!Required
    6-digit PIN code.
    stateString!Required
    State name.
    contacts[CustomerContact!]!Required
    People at the customer, at most 20.
    Show children
    designationStringOptional
    Job title.
    emailStringOptional
    Email address.
    idID!Required
    Stable id (UUIDv7).
    nameString!Required
    Full name.
    phoneStringOptional
    Phone number.
    createdAtString!Required
    UTC time the customer was added.
    emailStringOptional
    Main email.
    gstinStringOptional
    GSTIN, if registered.
    Example: "33DEMOA0001A1Z5"
    idID!Required
    Stable id (UUIDv7).
    Example: "0192f0c1-0000-7000-8000-0000000c0001"
    nameString!Required
    Company name.
    Example: "Alpha Auto Components 1"
    paymentTermsDaysInt!Required
    Days after the invoice date that payment is due; 0 = on delivery.
    phoneStringOptional
    Main phone.
    Example: "+91 98000 10001"
    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.
- pageInfoPageInfo!Required
  Whether more pages exist, and the cursors to reach them.
  Example: {"hasNextPage":true,"hasPreviousPage":false,"endCursor":"WyJhbHBoYSBhdXRvIGNvbXBvbmVudHMgMzciLCIwMTkyZjBjMS0wMDAwLTcwMDAtODAwMC0wMDAwMDAwYzAwMjUiXQ"}
  Show children
  - endCursorStringOptional
    Cursor of the last row; pass it as after to get the next page. Null when the page is empty.
    Example: "WyJhbHBoYSBhdXRvIGNvbXBvbmVudHMgMzciLCIwMTkyZjBjMS0wMDAwLTcwMDAtODAwMC0wMDAwMDAwYzAwMjUiXQ"
  - hasNextPageBoolean!Required
    Whether another page follows this one.
    Example: true
  - hasPreviousPageBoolean!Required
    Whether another page comes before this one.
    Example: false
  - startCursorStringOptional
    Cursor of the first row; pass it as before to page backwards. Null when the page is empty.
- totalCountInt!Required
  All rows matching the filter and search, not just this page.
  Example: 45

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.