Customer - REST Binding¶

This document specifies the HTTP/REST binding for the Customer Capability.

Protocol Fundamentals¶

Discovery¶

Participants advertise Customer REST availability through the protocol discovery document, including capability name, transport (rest), and endpoint base URL.

Authentication¶

All endpoints require bearerAuth (HTTP Bearer JWT).

Content Type¶

Request content type: application/json
Response content type: application/json

Base URL¶

Example base URL from committee draft:

https://api.opendelivery.io/v2

Operations¶

Operation	Method	Path	Entity	Description
List Customers	GET	`/customers`	Customer	Retrieve all customers
Upsert Customers	POST	`/customers`	Customer	Create or update customers in batch
Get Customer By ID	GET	`/customers/{id}`	Customer	Retrieve a specific customer by identifier
List Leads	GET	`/customers/leads`	Lead	Retrieve all leads
Upsert Leads	POST	`/customers/leads`	Lead	Create or update leads in batch
List Orders	GET	`/customers/orders`	Order	Retrieve all orders
Upsert Orders	POST	`/customers/orders`	Order	Create or update orders in batch
Get Order By ID	GET	`/customers/orders/{id}`	Order	Retrieve a specific order by identifier
Create Review	POST	`/customers/reviews`	Review	Create a new review
List Reviews	GET	`/customers/reviews`	Review	Retrieve all reviews
List Customer Reviews	GET	`/customers/{customerId}/reviews`	Review	Retrieve reviews for a specific customer

List Customers¶

Method and path: GET /customers

Input Schema¶

Field	Type	Required	Description
query params	object	No	Optional implementation-specific filters

Output Schema¶

Field	Type	Required	Description
body	array[Customer]	Yes	Customer list

Example¶

RequestResponse (200)

GET /customers HTTP/1.1
Host: api.opendelivery.io
Authorization: Bearer {token}
Accept: application/json

[
  {
    "identifier": {
      "type": "phone",
      "value": "+5511999999999"
    },
    "name": "Maria Silva"
  }
]

Upsert Customers¶

Method and path: POST /customers

Input Schema¶

Field	Type	Required	Description
body	array[Customer]	Yes	Customers to create/update

Output Schema¶

Field	Type	Required	Description
status	integer	Yes	`200` on success

Example¶

RequestResponse (200)

POST /customers HTTP/1.1
Host: api.opendelivery.io
Authorization: Bearer {token}
Content-Type: application/json

[
  {
    "identifier": {
      "type": "external_id",
      "value": "crm:customer:93821"
    },
    "name": "Maria Silva"
  }
]

No body

Get Customer By ID¶

Method and path: GET /customers/{id}

Input Schema¶

Field	Type	Required	Description
`id`	string	Yes	Customer identifier

Output Schema¶

Field	Type	Required	Description
body	Customer	Yes	Customer payload

Example¶

RequestResponse (200)

GET /customers/cust-001 HTTP/1.1
Host: api.opendelivery.io
Authorization: Bearer {token}
Accept: application/json

{
  "identifier": {
    "type": "external_id",
    "value": "cust-001"
  },
  "name": "Maria Silva"
}

List Leads¶

Method and path: GET /customers/leads

Input Schema¶

Field	Type	Required	Description
query params	object	No	Optional implementation-specific filters

Output Schema¶

Field	Type	Required	Description
body	array[Lead]	Yes	Lead list

Example¶

RequestResponse (200)

GET /customers/leads HTTP/1.1
Host: api.opendelivery.io
Authorization: Bearer {token}
Accept: application/json

[
  {
    "id": "lead-001",
    "name": "Ana Souza",
    "contact": "ana.souza@example.com"
  }
]

Upsert Leads¶

Method and path: POST /customers/leads

Input Schema¶

Field	Type	Required	Description
body	array[Lead]	Yes	Leads to create/update

Output Schema¶

Field	Type	Required	Description
status	integer	Yes	`200` on success

Example¶

RequestResponse (200)

POST /customers/leads HTTP/1.1
Host: api.opendelivery.io
Authorization: Bearer {token}
Content-Type: application/json

[
  {
    "id": "lead-001",
    "name": "Ana Souza",
    "contact": "ana.souza@example.com"
  }
]

No body

List Orders¶

Method and path: GET /customers/orders

Input Schema¶

Field	Type	Required	Description
query params	object	No	Optional implementation-specific filters

Output Schema¶

Field	Type	Required	Description
body	array[Order]	Yes	Order list

Example¶

RequestResponse (200)

GET /customers/orders HTTP/1.1
Host: api.opendelivery.io
Authorization: Bearer {token}
Accept: application/json

[
  {
    "id": "ord-001",
    "status": "CONFIRMED",
    "customer": {
      "id": "cust-001"
    }
  }
]

Upsert Orders¶

Method and path: POST /customers/orders

Input Schema¶

Field	Type	Required	Description
body	array[Order]	Yes	Orders to ingest

Output Schema¶

Field	Type	Required	Description
status	integer	Yes	`201` on success

Example¶

RequestResponse (201)

POST /customers/orders HTTP/1.1
Host: api.opendelivery.io
Authorization: Bearer {token}
Content-Type: application/json

[
  {
    "id": "ord-001",
    "status": "CONFIRMED",
    "customer": {
      "id": "cust-001"
    }
  }
]

No body

Get Order By ID¶

Method and path: GET /customers/orders/{id}

Input Schema¶

Field	Type	Required	Description
`id`	string	Yes	Order identifier

Output Schema¶

Field	Type	Required	Description
body	Order	Yes	Order payload

Example¶

RequestResponse (200)

GET /customers/orders/ord-001 HTTP/1.1
Host: api.opendelivery.io
Authorization: Bearer {token}
Accept: application/json

{
  "id": "ord-001",
  "status": "DELIVERED",
  "customer": {
    "id": "cust-001"
  }
}

Create Review¶

Method and path: POST /customers/reviews

Input Schema¶

Field	Type	Required	Description
body	Review	Yes	Review payload

Output Schema¶

Field	Type	Required	Description
status	integer	Yes	`201` on success

Example¶

RequestResponse (201)

POST /customers/reviews HTTP/1.1
Host: api.opendelivery.io
Authorization: Bearer {token}
Content-Type: application/json

{
  "reviewId": "rev-001",
  "reviewType": "ORDER",
  "overallRating": {
    "ratingStyle": "STAR",
    "value": 5,
    "comment": "Great experience"
  },
  "subject": {
    "orderId": "ord-001"
  },
  "customer": {
    "customerId": "cust-001"
  },
  "reviewDate": "2026-06-01T12:00:00Z"
}

No body

List Reviews¶

Method and path: GET /customers/reviews

Input Schema¶

Field	Type	Required	Description
query params	object	No	Optional implementation-specific filters

Output Schema¶

Field	Type	Required	Description
body	array[Review]	Yes	Review list

Example¶

RequestResponse (200)

GET /customers/reviews HTTP/1.1
Host: api.opendelivery.io
Authorization: Bearer {token}
Accept: application/json

[
  {
    "reviewId": "rev-001",
    "reviewType": "ORDER",
    "overallRating": {
      "ratingStyle": "STAR",
      "value": 5
    },
    "reviewDate": "2026-06-01T12:00:00Z"
  }
]

List Customer Reviews¶

Method and path: GET /customers/{customerId}/reviews

Input Schema¶

Field	Type	Required	Description
`customerId`	string	Yes	Customer identifier

Output Schema¶

Field	Type	Required	Description
body	array[Review]	Yes	Reviews for the customer

Example¶

RequestResponse (200)

GET /customers/cust-001/reviews HTTP/1.1
Host: api.opendelivery.io
Authorization: Bearer {token}
Accept: application/json

[
  {
    "reviewId": "rev-001",
    "reviewType": "ORDER",
    "overallRating": {
      "ratingStyle": "STAR",
      "value": 4
    },
    "customer": {
      "customerId": "cust-001"
    },
    "reviewDate": "2026-06-01T12:00:00Z"
  }
]

Error Handling¶

UCP-style two-layer interpretation applies: transport-level failures use HTTP status, while business semantics are expressed by endpoint responses and payloads.

Transport Errors¶

HTTP	Description
`400`	Bad request (defined in committee OpenAPI)
`401`	Unauthorized (auth policy)
`403`	Forbidden (authz policy)
`404`	Not found (resource path/ID resolution)
`500`	Internal server error

Business Outcomes¶

Business outcomes are represented by endpoint-specific success responses (200, 201) and response payloads (Customer, Lead, Order, Review).

Entities¶

Customer Collection Response¶

Field	Type	Required	Description
body	array[Customer]	Yes	Customer list response

Lead Collection Response¶

Field	Type	Required	Description
body	array[Lead]	Yes	Lead list response

Order Collection Response¶

Field	Type	Required	Description
body	array[Order]	Yes	Order list response

Review Collection Response¶

Field	Type	Required	Description
body	array[Review]	Yes	Review list response

Error Response (`BadRequest`)¶

Field	Type	Required	Description
`code`	string	No	Machine-readable error code
`message`	string	No	Human-readable error message

Conformance¶

A conforming Customer REST implementation MUST:

Implement all advertised Customer operations in discovery metadata.
Enforce Bearer authentication on all operations.
Accept and return JSON payloads as defined by Customer and related schemas.
Support batch payloads where defined (POST /customers, POST /leads, POST /orders).
Return status codes consistent with this binding and committee OpenAPI.

For loyalty transport under Customer scope, see Loyalty - REST Binding.

Customer - REST Binding¶

Protocol Fundamentals¶

Discovery¶

Authentication¶

Content Type¶

Base URL¶

Operations¶

List Customers¶

Input Schema¶

Output Schema¶

Example¶

Upsert Customers¶

Input Schema¶

Output Schema¶

Example¶

Get Customer By ID¶

Input Schema¶

Output Schema¶

Example¶

List Leads¶

Input Schema¶

Output Schema¶

Example¶

Upsert Leads¶

Input Schema¶

Output Schema¶

Example¶

List Orders¶

Input Schema¶

Output Schema¶

Example¶

Upsert Orders¶

Input Schema¶

Output Schema¶

Example¶

Get Order By ID¶

Input Schema¶

Output Schema¶

Example¶

Create Review¶

Input Schema¶

Output Schema¶

Example¶

List Reviews¶

Input Schema¶

Output Schema¶

Example¶

List Customer Reviews¶

Input Schema¶

Output Schema¶

Example¶

Error Handling¶

Transport Errors¶

Business Outcomes¶

Entities¶

Customer Collection Response¶

Lead Collection Response¶

Order Collection Response¶

Review Collection Response¶

Error Response (BadRequest)¶

Conformance¶

Error Response (`BadRequest`)¶