Customer Data

Access and manage customer-related data including e-wallet balances, bulk imports, PDF tickets, and custom metadata.

E-Wallet & Balance

Retrieve e-wallet automatic reload configuration and balance history for a customer. Balance history tracks all e-wallet transactions (credits, debits, refunds).

{
  "status": 200,
  "code": "customer_ewallet_automatic_reload_succeed",
  "message": "Configuration retrieved successfully.",
  "data": {
    "automaticEwalletReloadActive": true,
    "automaticEwalletReloadMinBalance": 500,
    "automaticEwalletReloadAmount": 2000,
    "automaticEwalletReloadCardId": 12345
  }
}

{
  "status": 200,
  "code": "balance_count_succeed",
  "message": "Balance count retrieved.",
  "data": {
    "total": 142
  }
}

Customer Import

Bulk import customers from a file. The endpoint accepts a file upload and processes it asynchronously, streaming progress updates back to the client via chunked transfer encoding.

multipart/form-data with a 'file' field containing the CSV or Excel file.

{
  "status": 200,
  "code": "customers_import_create_succeed",
  "message": "Import completed successfully.",
  "data": {
    "customersCreated": 15,
    "customersUpdated": 3,
    "customersUnchanged": 82
  }
}

file=[binary]

{
  "status": 200,
  "code": "customers_import_create_succeed",
  "message": "Customers have been imported successfully.",
  "data": {
    "customersCreated": 15,
    "customersUpdated": 3,
    "customersUnchanged": 82,
    "customersError": [
      {
        "line": 7,
        "email": "invalid@example.com",
        "invalidFields": [
          "email"
        ]
      }
    ],
    "customersWarn": [
      {
        "line": 8,
        "email": "duplicate@example.com",
        "invalidFields": [
          "email"
        ]
      }
    ],
    "otherWarnings": [
      {
        "type": "pricingRule",
        "list": [
          "UNKNOWN-RULE"
        ]
      }
    ],
    "validationErrors": []
  }
}

Customer Base Export

Export a filtered customer base directly as CSV or XLSX. If a large export cannot complete within the synchronous request window, request the asynchronous report instead and retrieve it from report generation.

Binary attachment. Content-Type is text/csv for csv or application/vnd.openxmlformats-officedocument.spreadsheetml.sheet for xlsx; Content-Disposition contains the filename.

{
  "status": 200,
  "code": "customer_base_export_request_created",
  "message": "Customer base export request is created successfully."
}

Retrieve Generated Reports

An asynchronous export is made available through report generation. Brand and restaurant users see only reports they created. Admin and brand-group users must provide brandId when they do not have a brand context, and can include impersonatedUserId to see reports created by that user.

{
  "status": 200,
  "code": "report_generations_succeed",
  "message": "The list of report generations have been found.",
  "data": [
    {
      "reportGenerationId": 812,
      "name": "customer-base-export-3325-2026-07-11.xlsx",
      "createdAt": "Fri Jul 11 2026 09:15:00 GMT+0000 (Coordinated Universal Time)",
      "reportType": "customer_base_export",
      "status": "succeed",
      "expired": false
    }
  ]
}

{
  "status": 200,
  "code": "report_generations_succeed",
  "message": "The list of report generations have been found.",
  "data": {
    "url": "https://storage.googleapis.com/<signed-report-url>"
  }
}

{
  "status": 200,
  "code": "customer_unarchive_succeed",
  "message": "Customer has been successfully unarchived.",
  "data": {
    "success": true
  }
}

Customer Tickets

Generate PDF receipts for individual orders or export a customer's receipt history as a PDF. Bulk exports can be counted and paginated before downloading to keep large histories manageable.

Single Ticket PDF

Binary PDF file (Content-Type: application/pdf). The response is an attachment; read the filename from the Content-Disposition response header.

Bulk PDF Export

First count the selected customer history, then request a PDF. For very large histories, uselimit and offset to retrieve bounded batches. A date range must include bothstartDate and endDate.

{
  "count": 142
}

Binary PDF file (Content-Type: application/pdf). Read the total matching ticket count from X-Total-Count and the filename from Content-Disposition.

Customer Metadata

Metadata entries belong to a customer and a brand. Each entry exposes customerMetadataId, customerId, brandId, namespace, data, createdAt and updatedAt. Older entries can have a null namespace. Use the explicit entry endpoints below for new integrations; the historical upsert and delete contracts remain available.

Authentication and scope

Send an authenticated bearer token. Every operation checks access to the brand and verifies that the customer belongs to it. Entry operations also verify that the entry belongs to that same customer and brand. The new /entries mutations accept Admin and Brand accounts only. Restaurant accounts have read-only metadata controls in the backoffice. The historical metadata routes retain their Admin, Brand, Restaurant and POS role allowlist for compatibility, subject to the brand-access checks; this does not grant those roles access to the new mutations.

Text, JSON and concurrency

• mode is required on entry creation and update: text or json. The request data is always a string, including an empty string in text mode.
• Text mode preserves the value literally. JSON mode parses the string once and stores its native JSON type: object, array, number, boolean, string or JSON null. Without a business schema, validation means valid JSON syntax.
• For a JSON object, use JSON mode and serialize the object once into the request's string-valued data field, as in the creation example below. For the literal text {"enabled":true}, use text mode. JSON null is sent as {"mode":"json","data":"null"}.
• Existing JSON-encoded strings remain readable. Depending on the storage/transport layer, returned data may be JSON text; do not recursively parse arbitrary strings or infer the write mode from a JSON-looking value. Preserve text values as text when editing; the backoffice can format legacy JSON strings for display.
• Read the entry first. Send its exact updatedAt in the JSON body of PUT or DELETE as the expected version. On 409, reload, reconcile the changes and submit the fresh version; do not blindly overwrite.
• The namespace is required, trimmed, non-empty and at most 255 characters on creation. It cannot be renamed by PUT. Updates/deletions use the returned customerMetadataId as the path metadataId, including for old entries whose namespace is null.

{
  "status": 200,
  "code": "customer_metadata_fetched",
  "message": "The customer metadata has been fetched.",
  "data": [
    {
      "customerMetadataId": 1234,
      "customerId": 5337578,
      "brandId": 100,
      "namespace": "preferences",
      "data": {
        "preferredLanguage": "fr",
        "enabled": true
      },
      "createdAt": "2026-09-21T09:00:00.000Z",
      "updatedAt": "2026-09-21T09:00:00.000Z"
    }
  ]
}

{
  "namespace": "preferences",
  "mode": "json",
  "data": "{\"preferredLanguage\":\"fr\",\"enabled\":true}"
}

{
  "status": 200,
  "code": "customer_metadata_saved",
  "message": "The customer metadata has been saved.",
  "data": {
    "customerMetadataId": 1234,
    "customerId": 5337578,
    "brandId": 100,
    "namespace": "preferences",
    "data": {
      "preferredLanguage": "fr",
      "enabled": true
    },
    "createdAt": "2026-09-21T09:00:00.000Z",
    "updatedAt": "2026-09-21T09:00:00.000Z"
  }
}

{
  "mode": "json",
  "data": "{\"preferredLanguage\":\"en\",\"enabled\":true}",
  "updatedAt": "2026-09-21T09:00:00.000Z"
}

{
  "status": 200,
  "code": "customer_metadata_saved",
  "message": "The customer metadata has been saved.",
  "data": {
    "customerMetadataId": 1234,
    "customerId": 5337578,
    "brandId": 100,
    "namespace": "preferences",
    "data": {
      "preferredLanguage": "en",
      "enabled": true
    },
    "createdAt": "2026-09-21T09:00:00.000Z",
    "updatedAt": "2026-09-21T09:05:00.000Z"
  }
}

{
  "updatedAt": "2026-09-21T09:05:00.000Z"
}

{
  "status": 200,
  "code": "customer_metadata_deleted",
  "message": "The customer metadata has been deleted.",
  "data": {}
}

Entry error responses

• 400 customer_metadata_invalid: invalid JSON content or invalid provenance context. Missing or malformed request fields can instead fail schema validation with HTTP 400.
• 409 customer_metadata_conflict: duplicate namespace on POST, or stale version on PUT/DELETE.
• 403 customer_metadata_forbidden: manual mutation of the reserved namespace. Authentication, role and brand authorization failures also apply and may use the API's standard permission errors.
• 404 customer_metadata_missing: customer or entry not found in the requested brand/customer scope.

Historical integration contracts

These routes keep their string payloads and do not accept the new mode/version fields. Prefer the entry endpoints when you need explicit creation or conflict detection.

{
  "namespace": "external_ids",
  "data": "{\"externalId\":\"EXT-99887\"}"
}

{
  "status": 200,
  "code": "customer_metadata_saved",
  "message": "The customer metadata has been saved.",
  "data": {
    "customerMetadataId": 1235,
    "customerId": 5337578,
    "brandId": 100,
    "namespace": "external_ids",
    "data": "{\"externalId\":\"EXT-99887\"}",
    "createdAt": "2026-09-21T09:00:00.000Z",
    "updatedAt": "2026-09-21T09:00:00.000Z"
  }
}

{
  "status": 200,
  "code": "customer_metadata_deleted",
  "message": "The customer metadata has been deleted.",
  "data": {}
}

Optional Customer Provenance

innovorder.provenance is reserved and managed by the API. Do not write it through any metadata endpoint. Instead, authenticated staff/integration callers may include an optional provenance object in POST /brands/{brandId}/customers, PUT /customers/{customerId} or PUT /brands/{brandId}/customers/loader. The loader accepts Admin/Brand accounts. Customer self-service callers cannot submit an external provenance context.

Backward compatibility: existing creation, update and loader payloads remain valid without provenance. Omitting it does not activate tracking, erase an existing origin or stop tracking a customer that already has valid provenance. For HTTP, omit the field when unused; its nested fields are required only when it is supplied.

Provenance request fields

• source (required): id and label, non-empty strings up to 255 characters; channel, non-empty string up to 64 characters. Supply a stable integration ID and a readable source label.
• entryMode (required): non-empty string up to 64 characters, for example form, import or manual. Channel and mode are generic strings, not enumerations.
• reference (optional): external request/import reference, up to 255 characters, or null.
• actors (required): array of up to 10 declared actors; it may be empty. Each actor requires non-empty id and displayName (up to 255 characters), and role (up to 64). Roles such as requester and approver distinguish the participants. Names are snapshots, not live lookups.
• at, authenticatedActor and the stored document's version are assigned by the API, not accepted as provenance request fields.

Example fragment to add to an otherwise valid customer creation/update/loader body:

{
  "provenance": {
    "source": {
      "id": "client-portal",
      "label": "Client portal",
      "channel": "portal"
    },
    "entryMode": "form",
    "reference": "request-123",
    "actors": [
      {
        "id": "portal:user:42",
        "displayName": "Alice Dupont",
        "role": "requester"
      },
      {
        "id": "portal:user:84",
        "displayName": "Theo Martin",
        "role": "approver"
      }
    ]
  }
}

An EDI connector supplies its own source, for example { id: "edi-connector", label: "EDI import", channel: "edi" }, with entryMode: "import". For manual entry by an approver, use entryMode: "manual" and an actor with role: "approver"; this contract does not introduce a new portal workflow. The authenticated account is recorded separately from these declared participants.

Stored document and lifecycle

The metadata entry contains a versioned document with optional creation and lastModification events. Example decoded data:

{
  "version": 1,
  "creation": {
    "at": "2026-09-21T09:00:00.000Z",
    "source": {
      "id": "client-portal",
      "label": "Client portal",
      "channel": "portal"
    },
    "entryMode": "form",
    "reference": "request-123",
    "actors": [
      {
        "id": "portal:user:42",
        "displayName": "Alice Dupont",
        "role": "requester"
      },
      {
        "id": "portal:user:84",
        "displayName": "Theo Martin",
        "role": "approver"
      }
    ],
    "authenticatedActor": {
      "id": "innovorder:user:12",
      "displayName": "Portal integration",
      "role": "operator"
    }
  }
}

• Only an explicit provenance context initializes tracking. A new customer gets a creation event. For an existing customer, the first effective change with context records only lastModification; the API never reconstructs its origin.
• After activation, effective profile, student/pricing/validity/status, badge and non-reserved metadata changes update lastModification, even without a new external context. The creation event stays unchanged. Identical reimports and unchanged metadata values do not replace the last trace.
• The API supplies the server timestamp and available authenticated identity. Generic changes use an Innovorder/API source; staff and self-service customers have distinct actor identities. Declared requester/approver actors are claims from the authenticated integration, not independently authenticated accounts.
• Changing another metadata entry does not activate provenance. Reserved internal writes do not recursively create a new trace. Data and provenance are written in the same transaction, with writes serialized per customer.
• Credentials/authentication, orders and wallet movements are excluded. This is creation plus latest modification, not a complete audit history. Direct maintenance SQL/model writes are outside application tracking.
• The backoffice displays Traceability only when the namespace contains a valid version-1 document with at least one event. Missing, empty or invalid provenance produces no section. Its metadata row is read-only and marked as automatically managed.

HTTP, Pub/Sub and rollout

Customer commands can carry the same optional provenance context through HTTP and the import Pub/Sub pipeline. The Avro customer command adds a nullable provenance field with default null; the consumer supports existing serialized commands as well as new ones. Old producers do not need to populate it. This is a command context, not a direct write to the reserved metadata namespace.

Deploy the compatible API and import consumer before enabling provenance in producers, then deploy the backoffice. No new table, historical backfill or full event history is required.