Skip to content
BILLZ for developers

Customers' purchases amount

PATCH
/v1/customer/bulk
curl --request PATCH \
  --url 'https://api-admin.billz.ai/v1/customer/bulk?Billz-Response-Channel=HTTP' \
  --header 'Authorization: Bearer <token>' \
  --header 'Billz-Response-Channel: HTTP' \
  --header 'Content-Type: application/json' \
  --header 'platform-id: 7d4a4c38-dd84-4902-b744-0488b80a4c01' \
  --data '{ "customers": [ { "customer_id": "0c4bacfa-5a20-4ee0-befb-e2c27da19d0c", "purchase_amount": 2100000 }, { "customer_id": "2be17079-dead-45a2-9b27-c7a7ceaf1476", "purchase_amount": 650000 } ] }'

Asynchronous method. To receive the result synchronously over HTTP, pass the Billz-Response-Channel: HTTP header — otherwise the response will be 200 {"message": "<correlation_id>"}. Maximum wait is 600 seconds, after which 408 with error.code = TIMEOUT is returned.

Sets the total purchases amount of customers: the new value replaces the current one rather than being added to it. Up to 1000 customers per request, request body no larger than 1 MB.

All or nothing: if at least one customer is not found in the company, nobody is updated, and the 404 response lists the customers not found.

Zero and negative amounts are allowed. Deleted and archived customers are updated too.

Error codes: 408 — timed out waiting for the asynchronous result; 401, 403, 429, 500 — shared by all methods. Body formats and semantics: Response codes and errors.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
platform-id
string
default: 7d4a4c38-dd84-4902-b744-0488b80a4c01

Platform identifier. A static value is used for integrations.

Billz-Response-Channel
string
Allowed values: HTTP

HTTP — wait for the event processing result and return it in the HTTP response. Without the header the method returns only the correlation_id of the published event.

Query Parameters

Section titled “Query Parameters”
Billz-Response-Channel
string
Allowed values: HTTP

Same as the Billz-Response-Channel header — for clients that cannot send a custom header. If both are passed, the header applies.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
customers
required

Customers and their new purchases amounts; a customer must not be repeated

Array<object>
>= 1 items <= 1000 items
object
customer_id
required

Customer ID

string format: uuid
purchase_amount
required

Total purchases amount; replaces the current one

number format: double
Example
{
  "customers": [
    {
      "customer_id": "0c4bacfa-5a20-4ee0-befb-e2c27da19d0c",
      "purchase_amount": 2100000
    },
    {
      "customer_id": "2be17079-dead-45a2-9b27-c7a7ceaf1476",
      "purchase_amount": 650000
    }
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

Success. With the Billz-Response-Channel: HTTP header — the asynchronous response envelope, without it — {"message": "<correlation_id>"}.

Media typeapplication/json
One of:
object
session_id

Customer session identifier

string format: uuid
status_code

Final HTTP code, 200

integer
correlation_id

Request identifier

string format: uuid
topic

Response event type, for example <event_type>.success

string
data
object
updated

How many customers were updated

integer
Example
{
  "session_id": "7c2a0f3e-3c52-4a4a-9d0e-5d3a8f1b2c11",
  "status_code": 200,
  "topic": "v1.user_service.customer.bulk_patch.success",
  "data": {
    "updated": 2
  }
}

400

Section titled “400”

The request was not accepted, nobody was updated. With an unknown field in the body, with invalid JSON or with a body larger than 1 MB — 400 immediately, without an envelope. Other reasons come in the envelope, the code is in data.error_code:

  • 1007 — the customers list is empty;
  • 1008 — more than 1000 customers;
  • 1009 — customer_id is not a UUID;
  • 1010 — a customer is repeated in the request;
  • 1011 — purchase_amount is not passed for a customer.

Validation stops at the first error; for 1009–1011 data.data holds that customer’s customer_id as a string.

Media typeapplication/json
One of:

Error body. Several error body formats coexist in the API; all formats and codes are described in the “Response codes and errors” section.

object
code

HTTP code or internal numeric error code

integer
message

Human-readable message

string
error
One of:
string
data

Payload (usually null on error)

object
Examplegenerated
{
  "code": 1,
  "message": "example",
  "error": {
    "code": "example",
    "message": "example"
  },
  "data": {}
}

404

Section titled “404”

At least one customer was not found in the company, nobody was updated. data.error_code = 1012, data.data holds missing_customer_ids (no more than 100) and missing_total — how many were not found in total.

Media typeapplication/json
One of:

Error body. Several error body formats coexist in the API; all formats and codes are described in the “Response codes and errors” section.

object
code

HTTP code or internal numeric error code

integer
message

Human-readable message

string
error
One of:
string
data

Payload (usually null on error)

object
Example
{
  "session_id": "7c2a0f3e-3c52-4a4a-9d0e-5d3a8f1b2c11",
  "status_code": 404,
  "topic": "v1.user_service.customer.bulk_patch.failed",
  "data": {
    "error_code": 1012,
    "message": "customers not found, nothing was updated",
    "data": {
      "missing_customer_ids": [
        "2be17079-dead-45a2-9b27-c7a7ceaf1476"
      ],
      "missing_total": 1
    }
  }
}