Batch create program members

Schedules asynchronous batch creation of program members. The request body is a JSON array of member entries (maximum body size is 10 MB). The request is processed asynchronously in batches of 100 entries.

The program must exist (otherwise, it returns a 404 error) and be in ACTIVE status (otherwise, it returns a 423 error). Supported member fields are validated during background processing using the same domain validation rules as single member creation. Entries that fail validation (missing/invalid customer_id, unknown customer, invalid status, duplicate customer_id within the same batch, member already exists) are reported per-entry individually in the report linked from the async action result. The failed entries do not fail the whole batch (conflicting members are skipped).

Returns 202 status with the identifier of the scheduled async action. Use the GET Async Action endpoint to check the status of the batch creation. You can also check the processing status and the result in the Audit log – Background tasks in the Voucherify dashboard.

POST /v2/loyalties/programs/{programId}/members/batch

Error

A valid request URL is required to generate request examples

202

{
  "async_action_id": "aa_12c30928a207efcc66"
}

{
  "code": 404,
  "key": "not_found",
  "message": "Resource not found",
  "details": "Cannot find program with id lprg_128f5829f4c4bf7b2",
  "request_id": "v-12c31c59130a67bb28",
  "resource_id": "lprg_128f5829f4c4bf7b2",
  "resource_type": "program"
}

{
  "statusCode": 413,
  "error": "Request Entity Too Large",
  "message": "Payload content length greater than maximum allowed: 10485760"
}

{
  "code": 423,
  "key": "non_active_program",
  "message": "Invalid program status",
  "details": "Cannot create members when program status is not ACTIVE",
  "request_id": "v-12c31c59130a67bb28"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>",
  "resource_id": "<string>",
  "resource_type": "<string>"
}

Authorizations

X-App-Id & X-App-TokenbearerAuth

X-App-Id · string · header · required

X-App-Token · string · header · required

Path Parameters

programId · string · required

Unique loyalty program ID (format lprg_[a-f0-9]+).

Pattern: ^lprg_[a-f0-9]+$

Body

application/json

customer_id · string · required

Unique Voucherify customer ID of an existing customer to enroll as a member. Required.

Pattern: ^cust_[a-zA-Z0-9]+

status · enum<string> | null · default: ACTIVE

Initial member status. Defaults to ACTIVE when omitted or null.

Available options: ACTIVE, INACTIVE

metadata · object | null

Free-form metadata attached to the member. Validated against the metadata schema defined for the vl_member related object (when one is configured). Defaults to an empty object.

Response

202

application/json

Batch creation has been scheduled.

Result of scheduling the members batch creation.

async_action_id · string · required

ID of the scheduled async action processing the batch.

Pattern: ^aa_[a-f0-9]+$