Minimum APIs for an Ecommerce Customer Support Agent

An ecommerce customer support agent needs two required API capabilities and one conditional capability:

Order list — find orders using the customer's phone number or email address.
Order details — retrieve the complete support view for a selected order ID.
Customer details — retrieve the customer profile using a phone number or email address, but only when the order-list response does not already contain the required customer details.

Minimum integration

Implement Order list and Order details for every integration. You can skip Customer details when each order-list result includes sufficient customer information for support workflows.

The endpoint names and paths below are illustrative. An integration can use different routes as long as it provides the same capabilities and fields.

Request sequence

The agent should use the APIs in this order:

Accept either a phone number or an email address from the customer.
Normalize the identifier and call the Order list API.
If several orders are returned, ask the customer to select one using safe summary fields such as order number, date, status, and total.
Use the selected order_id to call the Order details API.
Check whether the Order list response already contains the required customer details.
Call the Customer details API only when that customer context is missing.

The agent must not invent missing customer or order information. If a required field is unavailable, the agent should explain the limitation or transfer the conversation according to the support workflow.

1. Order list API

The Order list API finds candidate orders using a customer-supplied phone number or email address.

Example request

GET /orders?email=customer@example.com

or:

GET /orders?phone=%2B919876543210

At least one identifier must be present. If the endpoint accepts both identifiers in the same request, document whether they are combined using AND or OR matching.

Input requirements

Input	Requirement	Guidance
`email`	Required when `phone` is absent	Trim whitespace and use case-insensitive comparison.
`phone`	Required when `email` is absent	Normalize to E.164 format where possible and retain the country context.
`cursor` or page token	Optional	Use when the customer has more orders than fit in one response.
`limit`	Optional	Apply a safe server-side maximum.

Use exact normalized matching by default. If an integration supports fuzzy matching, it should return match confidence and require confirmation before the agent reveals order information.

Minimum response fields

Field	Requirement	Purpose
`order_id`	Must	Stable identifier used by the Order details API.
`order_number`	Should	Human-friendly value the customer can recognize.
`created_at`	Must	Helps distinguish recent and historical orders.
`order_status`	Must	Provides immediate order-state context.
`fulfillment_status`	Should	Distinguishes processing, shipped, and delivered orders.
`total.amount`	Must	Helps confirm the selected order and answer billing questions.
`total.currency`	Must	Gives the amount an unambiguous currency.
`customer`	Conditional	Can eliminate the separate Customer details API when it contains sufficient customer context.
`next_cursor`	Conditional	Required when more results are available.

Return orders newest first.

Example response

{
  "orders": [
    {
      "order_id": "ord_123",
      "order_number": "10482",
      "created_at": "2026-07-18T10:42:00Z",
      "order_status": "confirmed",
      "fulfillment_status": "shipped",
      "total": {
        "amount": "79.00",
        "currency": "USD"
      },
      "customer": {
        "customer_id": "cus_77",
        "name": "A. Rao",
        "email": "a***@example.com",
        "phone": "+91******3210"
      }
    }
  ],
  "next_cursor": null
}

For a valid lookup with no matching orders, return 200 OK with an empty array:

{
  "orders": [],
  "next_cursor": null
}

2. Order details API

The Order details API returns the authoritative support view for one order selected from the Order list response.

Example request

GET /orders/{order_id}

The API must accept the opaque order_id returned by the Order list API. The integration should not require the agent to reconstruct or transform this identifier.

Minimum response fields

Field group	Minimum fields
Identity	`order_id`, `order_number`, `created_at`, and `updated_at`
State	`order_status`, `fulfillment_status`, and `payment_status`
Items	Line-item ID, product or variant name, quantity, unit price, and line total
Amounts	Subtotal, discounts, shipping, tax, grand total, and currency
Fulfillment	Carrier, tracking number, tracking URL, and shipped or delivered timestamps when available
Shipping	Recipient name and delivery address allowed by the organization's support policy
Payment	Payment method type and masked payment reference only
Adjustments	Refund, return, or cancellation summaries and timestamps when applicable

Example response

{
  "order_id": "ord_123",
  "order_number": "10482",
  "created_at": "2026-07-18T10:42:00Z",
  "updated_at": "2026-07-19T07:10:00Z",
  "order_status": "confirmed",
  "payment_status": "paid",
  "fulfillment_status": "shipped",
  "items": [
    {
      "line_item_id": "li_1",
      "name": "Travel Mug",
      "variant": "Black",
      "quantity": 1,
      "unit_price": {
        "amount": "79.00",
        "currency": "USD"
      },
      "line_total": {
        "amount": "79.00",
        "currency": "USD"
      }
    }
  ],
  "totals": {
    "subtotal": { "amount": "79.00", "currency": "USD" },
    "discount": { "amount": "0.00", "currency": "USD" },
    "shipping": { "amount": "0.00", "currency": "USD" },
    "tax": { "amount": "0.00", "currency": "USD" },
    "grand_total": { "amount": "79.00", "currency": "USD" }
  },
  "fulfillments": [
    {
      "carrier": "Example Carrier",
      "tracking_number": "TRACK-REDACTED",
      "tracking_url": "https://carrier.example/track/TRACK-REDACTED",
      "shipped_at": "2026-07-19T07:10:00Z",
      "delivered_at": null
    }
  ],
  "payment": {
    "method": "card",
    "masked_reference": "Visa ending in 1234"
  }
}

The endpoint should return the current order state. Document any caching delay that may affect answers about fulfillment, refunds, or cancellations.

3. Customer details API

The Customer details API retrieves customer-level information using the same phone number or email address used for the order lookup.

This capability is conditional. It is required only when the Order list response does not contain enough customer information for the supported workflows.

Example request

GET /customers/lookup?email=customer@example.com

or:

GET /customers/lookup?phone=%2B919876543210

Minimum response fields

Field	Requirement	Guidance
`customer_id`	Must, when the platform creates customer records	Return a stable identifier.
`name`	Must	Return the display name suitable for agent use.
`email`	Must when queried by email	Return a masked or policy-approved value.
`phone`	Must when queried by phone	Return a normalized, masked, or policy-approved value.
`customer_type`	Should	For example, `registered` or `guest`.
`account_status`	Should	For example, `active`, `disabled`, or `deleted`.
`default_address`	Optional	Include only when a supported workflow requires it.

When this API can be skipped

The Customer details API can be omitted when every Order list result embeds a customer object containing all customer fields required by the support agent. At minimum, this will usually include:

A stable customer ID, when available
Customer name
The matched email address or phone number in a masked or policy-approved form
Customer type or account status, when those values affect the support workflow

{
  "order_id": "ord_123",
  "customer": {
    "customer_id": "cus_77",
    "name": "A. Rao",
    "email": "a***@example.com",
    "phone": "+91******3210",
    "customer_type": "registered",
    "account_status": "active"
  }
}

Skip rule

If the Order list response supplies the required customer context, use it and do not make a separate Customer details call.

Common API behavior

Use consistent status codes and stable machine-readable error codes across all three capabilities.

Situation	Recommended behavior
Invalid phone or email	`400 Bad Request` with an error such as `invalid_identifier`
No matching orders	`200 OK` with `orders: []`
Multiple matching orders	Return safe summary fields, newest first, and let the customer select an order
Unknown order ID	`404 Not Found` with `order_not_found`
Missing or invalid authentication	`401 Unauthorized`
Insufficient access	`403 Forbidden` without revealing whether the record exists
Rate limit reached	`429 Too Many Requests`, preferably with `Retry-After`
Temporary dependency failure	`503 Service Unavailable` with a retryable error code and request ID

Include a request or correlation ID in headers or response metadata so API calls can be traced during troubleshooting.

Security and data minimization

Use TLS and authenticated service-to-service access.
Scope access to the correct account, tenant, and store.
Grant read-only, least-privilege permissions for this minimum integration.
Apply the organization's customer-verification policy before revealing sensitive order data. A phone number or email address is an identifier, not proof of identity by itself.
Mask contact, address, and payment information unless the workflow explicitly requires the complete value.
Never return full card numbers, CVV values, passwords, access tokens, or unnecessary internal risk signals.
Audit access and follow the organization's data-retention and privacy policies.

Acceptance checklist

An email-only lookup returns a bounded, newest-first order list.
A phone-only lookup uses documented normalization and returns the same response shape.
Every order-list item contains an order_id accepted by the Order details API.
Order details include items, totals, order state, fulfillment, and masked payment context.
No-match, multiple-match, unauthorized, rate-limit, and dependency-failure cases are deterministic.
Customer details are requested only when the Order list response lacks required customer context.
If the Customer details API is omitted, the Order list customer object satisfies the documented minimum fields.
Logs and API payloads comply with privacy and retention policies.

Out of scope

Refunds, cancellations, returns, exchanges, address changes, payment retries, and other mutations require separate APIs. Those endpoints need additional authorization, policy validation, confirmation, audit, and idempotency controls and are not part of this minimum read-only contract.

Custom APIs — define endpoints the AI can call and designate source APIs for built-in ecommerce data.
Integrations — configure reusable connections, authentication, and API behavior.
Data Points — understand how order and customer values become available to workflows.

Request sequence​

1. Order list API​

Example request​

Input requirements​

Minimum response fields​

Example response​

2. Order details API​

Example request​

Minimum response fields​

Example response​

3. Customer details API​

Example request​

Minimum response fields​

When this API can be skipped​

Common API behavior​

Security and data minimization​

Acceptance checklist​

Out of scope​

Related​

Request sequence

1. Order list API

Example request

Input requirements

Minimum response fields

Example response

2. Order details API

Example request

Minimum response fields

Example response

3. Customer details API

Example request

Minimum response fields

When this API can be skipped

Common API behavior

Security and data minimization

Acceptance checklist

Out of scope

Related