Skip to content
BILLZ for developers

Card creation

POST
/v1/gift-card/activate-list
curl --request POST \
  --url 'https://api-admin.billz.ai/v1/gift-card/activate-list?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 '{ "id": 0, "is_activated": false, "gift_cards": [ { "code": "1000000001", "amount": 10000, "expire_period": "31.12.2024" } ], "card_type": "CERTIFICATE", "expire_type": "ABSOLUTE", "use_type": "SINGLE" }'

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.

The card list is created in the BILLZ interface (Marketing → Gift cards); there is no separate API method for creating a list. id is the identifier of an already created list; the method activates the cards in it.

Error codes: 400 — input validation error; 404 — object not found; 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
id

Identifier of an existing card list

integer format: int32
0
is_activated

Create a pre-activated card (VOUCHER only)

boolean
gift_cards

List of cards

Array<object>
object
code

Card code

string
amount

Face value

number
expire_period

Validity period; interpreted according to expire_type

card_type

CERTIFICATE | VOUCHER

string
expire_type

ABSOLUTE or RELATIVE

string
use_type

SINGLE | MULTIPLE

string
company_id
string
session_id
string
user
string
Example
{
  "id": 0,
  "is_activated": false,
  "gift_cards": [
    {
      "code": "1000000001",
      "amount": 10000,
      "expire_period": "31.12.2024"
    }
  ],
  "card_type": "CERTIFICATE",
  "expire_type": "ABSOLUTE",
  "use_type": "SINGLE"
}

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:

Asynchronous response envelope. Returned when the Billz-Response-Channel: HTTP header is passed. The final HTTP code of the request is taken from the status_code field.

object
session_id

Customer session identifier

string format: uuid
status_code

Event processing status (also the final HTTP response code)

integer
error
object
code

Error code, empty string if there is no error

string
message

Error text, empty string if there is no error

string
correlation_id

Request identifier, matches the ID of the published event

string format: uuid
topic

Response event type, for example <event_type>.success

string
data

Operation result, if the method returns one

object
Examplegenerated
{
  "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "status_code": 1,
  "error": {
    "code": "example",
    "message": "example"
  },
  "correlation_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "topic": "example",
  "data": {}
}