Skip to content
BILLZ for developers

Change sale date

PATCH
/v2/order/{id}
curl --request PATCH \
  --url 'https://api-admin.billz.ai/v2/order/5f6d2c0e-8a39-4c77-9a42-1d0a6d6f7a11?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 '{ "sold_at": "2023-05-14 18:32:10" }'

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.

Changes only the date (sold_at) of a completed sale, return or exchange. Products, amounts, payments, customer and document status stay the same.

The new date is passed in the company’s time zone and must follow these rules:

  • not later than the current moment and not earlier than 2000-01-01 00:00:00;
  • a return or exchange is not earlier than its original sale, a sale is not later than its first return or exchange;
  • if finance is enabled in the company and the document belongs to a cash register shift — within that shift, old dates included.

A repeated call with the same date returns 200 with changed: false.

Dates in the response are in UTC (RFC 3339), not in the company’s time zone as in the request.

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”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

ID of the sale, return or exchange

Example
5f6d2c0e-8a39-4c77-9a42-1d0a6d6f7a11

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
sold_at
required

New date and time in the company’s time zone, format YYYY-MM-DD HH:MM:SS

string
Example
{
  "sold_at": "2023-05-14 18:32:10"
}

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
id

ID of the sale, return or exchange

string format: uuid
data
object
order_id

ID of the sale, return or exchange

string format: uuid
order_type

Document type: sale, return or exchange

string
Allowed values: SALE RETURN EXCHANGE
old_sold_at

Date before the change, UTC

string format: date-time
sold_at

Date after the change, UTC

string format: date-time
changed

false if the date passed matched the current one and the document did not change

boolean
Example
{
  "session_id": "7c2a0f3e-3c52-4a4a-9d0e-5d3a8f1b2c11",
  "status_code": 200,
  "id": "5f6d2c0e-8a39-4c77-9a42-1d0a6d6f7a11",
  "topic": "v2.order_service.order.patch.success",
  "data": {
    "order_id": "5f6d2c0e-8a39-4c77-9a42-1d0a6d6f7a11",
    "order_type": "SALE",
    "old_sold_at": "2026-03-10T12:00:00Z",
    "sold_at": "2026-01-05T05:00:00Z",
    "changed": true
  }
}

400

Section titled “400”

The date was not accepted. Without sold_at, with other fields in the body or with invalid JSON — 400 immediately, without an envelope. Other reasons come in the envelope, the code is in data.error_code:

  • 20127 — the document is not completed;
  • 20128 — sold_at is not in the YYYY-MM-DD HH:MM:SS format;
  • 20129 — the date is in the future or earlier than 2000-01-01;
  • 20130 — a return or exchange is earlier than its original sale; data.data holds parent_order_id and parent_sold_at (UTC, YYYY-MM-DD HH:MM:SS);
  • 20131 — a sale is later than its first return or exchange; data.data holds child_order_id and child_sold_at (UTC, YYYY-MM-DD HH:MM:SS);
  • 20132, 20133 — the date is outside the cash register shift the document belongs to.
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": 400,
  "topic": "v2.order_service.order.patch.failed",
  "data": {
    "error_code": 20130,
    "message": "return or exchange can't be dated earlier than its sale",
    "data": {
      "parent_order_id": "a1000000-0000-4000-8000-000000000001",
      "parent_sold_at": "2026-03-10 12:00:00"
    }
  }
}

404

Section titled “404”

The document was not found in the company, data.error_code = 20088.

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": {}
}