Customers

Server

List customers

GET

https://api.wocart.store

/api/customers

X-API-Key (header)

Returns a paginated list of customers. Use groupId or tagId to filter by segment. Use wilayaId to filter by wilaya.

List customers › query Parameters

wilayaId

integer · min: 1 · max: 58

Filter by wilaya ID (1–58)

search

string

Search by customer name, phone or email

groupId

string

Filter to customers in a specific customer group

tagId

string

Filter to customers with a specific tag

limit

integer · max: 100

Maximum number of results to return

Default: 50

offset

integer | null · min: 0

Number of results to skip for pagination

Default: 0

List customers › Responses

200

List of customers

success

boolean · required

Customer[] · required

count

integer · required

Number of items returned

Create customer

POST

https://api.wocart.store

/api/customers

X-API-Key (header)

Create customer › Request Body

name

string · minLength: 1 · required

phone

string · pattern: ^0[5-7]\d{8}$ · required

Algerian mobile number starting with 05, 06, or 07

wilayaId

integer · min: 1 · max: 58 · required

Official wilaya number (1–58)

communeId

string · minLength: 1 · required

Commune UUID from /api/wilayas/{id}/communes

phone2

string | null · pattern: ^0[5-7]\d{8}$

Secondary phone number (optional)

email

string | null · email · maxLength: 254

Email address (optional); stored lower-cased

address

string

Create customer › Responses

Customer created. Response includes the full customer record with recentOrders (empty array for new customers).

success

boolean · required

Customer · required

Customer profile with denormalized purchase statistics

message

string · required

POST/api/customers

curl https://api.wocart.store/api/customers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "name": "Ahmed Benali",
  "phone": "0551234567",
  "phone2": "phone2",
  "email": "amina@example.com",
  "wilayaId": 16,
  "communeId": "550e8400-e29b-41d4-a716-446655440000",
  "address": "12 Rue Didouche Mourad"
}'

Example Request Body

{
  "name": "Ahmed Benali",
  "phone": "0551234567",
  "phone2": "phone2",
  "email": "amina@example.com",
  "wilayaId": 16,
  "communeId": "550e8400-e29b-41d4-a716-446655440000",
  "address": "12 Rue Didouche Mourad"
}

json

Example Responses

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Ahmed Benali",
    "phone": "0551234567",
    "phone2": null,
    "email": "amina@example.com",
    "wilayaId": 16,
    "communeId": "550e8400-e29b-41d4-a716-446655440000",
    "wilaya": "الجزائر",
    "commune": "بئر مراد رايس",
    "address": "address",
    "totalOrders": 5,
    "totalSpent": 25000,
    "createdAt": "2024-08-25T15:00:00Z",
    "lastOrderAt": "2024-08-25T15:00:00Z",
    "recentOrders": [
      {
        "key": {}
      }
    ]
  },
  "message": "Operation completed successfully"
}

json

application/json

Get customer

GET

https://api.wocart.store

/api/customers/{id}

X-API-Key (header)

Returns the full customer record plus recentOrders (up to 10 most recent orders).

Get customer › path Parameters

id

string · required

Customer ID

Get customer › Responses

200

Customer detail including recentOrders

success

boolean · required

Customer · required

Customer profile with denormalized purchase statistics

Update customer

PATCH

https://api.wocart.store

/api/customers/{id}

X-API-Key (header)

Partial update — only include fields you want to change. Set phone2, communeId, or address to null to clear them.

Update customer › path Parameters

id

string · required

Customer ID

Update customer › Request Body

name

string · minLength: 1

phone

string · pattern: ^0[5-7]\d{8}$

Algerian mobile number starting with 05, 06, or 07

phone2

string | null · pattern: ^0[5-7]\d{8}$

Secondary phone. Set to null to clear it.

email

string | null · email · maxLength: 254

Email address. Set to null or empty to clear it.

wilayaId

integer · min: 1 · max: 58

Official wilaya number (1–58)

communeId

string | null · minLength: 1

Commune UUID. Set to null to clear.

address

string | null

Street address. Set to null to clear it.

Update customer › Responses

Customer updated. Returns the full updated customer record.

success

boolean · required

Customer · required

Customer profile with denormalized purchase statistics

message

string · required

PATCH/api/customers/{id}

curl https://api.wocart.store/api/customers/:id \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "name": "Ahmed Benali",
  "phone": "0551234567",
  "phone2": "phone2",
  "email": "test@example.com",
  "wilayaId": 16,
  "communeId": "communeId",
  "address": "address"
}'

Example Request Body

{
  "name": "Ahmed Benali",
  "phone": "0551234567",
  "phone2": "phone2",
  "email": "test@example.com",
  "wilayaId": 16,
  "communeId": "communeId",
  "address": "address"
}

json

Example Responses

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Ahmed Benali",
    "phone": "0551234567",
    "phone2": null,
    "email": "amina@example.com",
    "wilayaId": 16,
    "communeId": "550e8400-e29b-41d4-a716-446655440000",
    "wilaya": "الجزائر",
    "commune": "بئر مراد رايس",
    "address": "address",
    "totalOrders": 5,
    "totalSpent": 25000,
    "createdAt": "2024-08-25T15:00:00Z",
    "lastOrderAt": "2024-08-25T15:00:00Z",
    "recentOrders": [
      {
        "key": {}
      }
    ]
  },
  "message": "Operation completed successfully"
}

json

application/json

Delete customer

DELETE

https://api.wocart.store

/api/customers/{id}

X-API-Key (header)

Permanently deletes the customer. Blocked with 422 if the customer has any orders — remove or reassign the orders first.

Delete customer › path Parameters

id

string · required

Customer ID

Delete customer › Responses

Customer permanently deleted

MessageResponse

success

boolean · required

message

string · required

Get customer orders

GET

https://api.wocart.store

/api/customers/{id}/orders

X-API-Key (header)

Returns all orders for a customer in reverse chronological order, each with statusHistory included.

Get customer orders › path Parameters

id

string · required

Customer ID

Get customer orders › Responses

200

List of customer orders (each includes statusHistory)

success

boolean · required

CustomerOrderSummary[] · required

count

integer · required

Number of items returned

Get customer groups

GET

https://api.wocart.store

/api/customers/{id}/groups

X-API-Key (header)

Returns all customer groups the customer belongs to, including the assignedAt timestamp for each membership.

Get customer groups › path Parameters

id

string · required

Customer ID

Get customer groups › Responses

200

List of groups the customer belongs to

success

boolean · required

CustomerGroupMembership[] · required

Get customer tags

GET

https://api.wocart.store

/api/customers/{id}/tags

X-API-Key (header)

Returns all tags assigned to the customer, including the assignedAt timestamp for each assignment.

Get customer tags › path Parameters

id

string · required

Customer ID

Get customer tags › Responses

200

List of tags assigned to the customer

success

boolean · required

CustomerTagMembership[] · required

Reviews Customer Groups