Promo Code

GET/api/v1/promo-codes/batches

List_batches

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Conditions as filter[][]=. Conditions on different fields all apply. in (any of) and all (every one of, on fields holding several values) take a comma-separated list (\, for a literal comma). exists takes true or false. Datetimes are RFC 3339, now, or a time before now such as -30m, -6h or -7d.

q?string

Full-text search over this list's searchable fields.

Length1 <= length <= 200

sort?string

Comma-separated sort keys, - for descending, at most 1. Keys: name, requested_count, updated_at, created_at. Default: -created_at.

limit?integer

Rows per page, 1 to 100 (default 25).

Range1 <= value <= 100

cursor?string

The page.next_cursor of the previous page. Cannot be combined with page.

page?integer

A 1-based page number, for jumping. Cannot be combined with cursor.

Range1 <= value

total?boolean

Set to true to include the number of matching rows in page.total.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/promo-codes/batches"

{  "batches": [    {      "batch_id": "string",      "caps": {        "global_redemptions": 0,        "per_code": 0,        "per_referrer": 0,        "per_user": 0      },      "claim_type": "single_use",      "claim_window": {        "ends_at": "2019-08-24T14:15:22Z",        "starts_at": "2019-08-24T14:15:22Z"      },      "created_at": "2019-08-24T14:15:22Z",      "created_by": "string",      "description": "string",      "geo_fence": {        "countries": [          "string"        ],        "mode": "allow"      },      "name": "string",      "quarantine_reason": "string",      "requested_count": 0,      "reward_payload": null,      "status": "draft",      "stored_value": {        "enabled": true,        "initial_value": 0,        "partial_redemption": true      },      "total_redemptions": 0,      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "page": {    "has_more": true,    "next_cursor": "string",    "page": 0,    "total": 0  }}

POST/api/v1/promo-codes/batches

Create_batch

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

caps?null|

claim_type?null|

claim_window?null|

code_policy?null|

count*integer

Number of unique codes to generate for the batch.

Formatint64

Range0 <= value

description?|

Optional campaign description.

geo_fence?null|

name*string

Human-readable campaign name.

reward_payload*unknown

Reward payload revealed only on successful redemption.

stored_value?null|

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/promo-codes/batches" \  -H "Content-Type: application/json" \  -d '{    "count": 0,    "name": "string",    "reward_payload": null  }'

{  "batch_id": "string",  "progress_url": "string",  "requested_count": 0,  "status": "draft"}

GET/api/v1/promo-codes/batches/{batch_id}

Get_batch

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

batch_id*string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/promo-codes/batches/string"

{  "batch_id": "string",  "caps": {    "global_redemptions": 0,    "per_code": 0,    "per_referrer": 0,    "per_user": 0  },  "claim_type": "single_use",  "claim_window": {    "ends_at": "2019-08-24T14:15:22Z",    "starts_at": "2019-08-24T14:15:22Z"  },  "created_at": "2019-08-24T14:15:22Z",  "created_by": "string",  "description": "string",  "geo_fence": {    "countries": [      "string"    ],    "mode": "allow"  },  "name": "string",  "quarantine_reason": "string",  "requested_count": 0,  "reward_payload": null,  "status": "draft",  "stored_value": {    "enabled": true,    "initial_value": 0,    "partial_redemption": true  },  "total_redemptions": 0,  "updated_at": "2019-08-24T14:15:22Z"}

POST/api/v1/promo-codes/batches/{batch_id}/archive

Archive_batch

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

batch_id*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/promo-codes/batches/string/archive"

{  "batch_id": "string",  "caps": {    "global_redemptions": 0,    "per_code": 0,    "per_referrer": 0,    "per_user": 0  },  "claim_type": "single_use",  "claim_window": {    "ends_at": "2019-08-24T14:15:22Z",    "starts_at": "2019-08-24T14:15:22Z"  },  "created_at": "2019-08-24T14:15:22Z",  "created_by": "string",  "description": "string",  "geo_fence": {    "countries": [      "string"    ],    "mode": "allow"  },  "name": "string",  "quarantine_reason": "string",  "requested_count": 0,  "reward_payload": null,  "status": "draft",  "stored_value": {    "enabled": true,    "initial_value": 0,    "partial_redemption": true  },  "total_redemptions": 0,  "updated_at": "2019-08-24T14:15:22Z"}

PATCH/api/v1/promo-codes/batches/{batch_id}/caps

Update_caps

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

batch_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

global_redemptions?|

Updated global redemption cap.

Formatint64

Range0 <= value

per_code?|

Updated per-code redemption cap for multi-use codes.

Formatint64

Range0 <= value

per_referrer?|

Updated per-referrer redemption cap.

Formatint64

Range0 <= value

per_user?|

Updated per-user redemption cap.

Formatint64

Range0 <= value

Response Body

`application/json`

curl -X PATCH "https://example.com/api/v1/promo-codes/batches/string/caps" \  -H "Content-Type: application/json" \  -d '{}'

{  "batch_id": "string",  "caps": {    "global_redemptions": 0,    "per_code": 0,    "per_referrer": 0,    "per_user": 0  },  "claim_type": "single_use",  "claim_window": {    "ends_at": "2019-08-24T14:15:22Z",    "starts_at": "2019-08-24T14:15:22Z"  },  "created_at": "2019-08-24T14:15:22Z",  "created_by": "string",  "description": "string",  "geo_fence": {    "countries": [      "string"    ],    "mode": "allow"  },  "name": "string",  "quarantine_reason": "string",  "requested_count": 0,  "reward_payload": null,  "status": "draft",  "stored_value": {    "enabled": true,    "initial_value": 0,    "partial_redemption": true  },  "total_redemptions": 0,  "updated_at": "2019-08-24T14:15:22Z"}

POST/api/v1/promo-codes/batches/{batch_id}/export

Export_batch

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

batch_id*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/promo-codes/batches/string/export"

{  "batch_id": "string",  "codes": [    {      "code_hash": "string",      "status": "string"    }  ],  "expires_at": "2019-08-24T14:15:22Z"}

POST/api/v1/promo-codes/batches/{batch_id}/quarantine

Quarantine_batch

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

batch_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

note?|

Optional operator note.

reason*string

Machine-readable quarantine reason.

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/promo-codes/batches/string/quarantine" \  -H "Content-Type: application/json" \  -d '{    "reason": "string"  }'

{  "batch_id": "string",  "reason": "string",  "status": "draft"}

GET/api/v1/promo-codes/batches/{batch_id}/redemptions

List_redemptions

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

batch_id*string

Query Parameters

filter?

sort?string

Comma-separated sort keys, - for descending, at most 1. Keys: redeemed_at. Default: -redeemed_at.

limit?integer

Rows per page, 1 to 100 (default 25).

Range1 <= value <= 100

cursor?string

The page.next_cursor of the previous page. Cannot be combined with page.

page?integer

A 1-based page number, for jumping. Cannot be combined with cursor.

Range1 <= value

total?boolean

Set to true to include the number of matching rows in page.total.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/promo-codes/batches/string/redemptions"

{  "page": {    "has_more": true,    "next_cursor": "string",    "page": 0,    "total": 0  },  "redemptions": [    {      "amount_redeemed": 0,      "batch_id": "string",      "campaign_id": "string",      "claim_type": "single_use",      "claimant_id": "string",      "code_hash": "string",      "country": "string",      "redeemed_at": "2019-08-24T14:15:22Z",      "redemption_id": "string",      "referrer_id": "string",      "status": "rejected"    }  ]}

POST/api/v1/promo-codes/batches/{batch_id}/resume

Resume_batch

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

batch_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

note?|

Optional operator note recorded in the audit trail.

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/promo-codes/batches/string/resume" \  -H "Content-Type: application/json" \  -d '{}'

{  "batch_id": "string",  "caps": {    "global_redemptions": 0,    "per_code": 0,    "per_referrer": 0,    "per_user": 0  },  "claim_type": "single_use",  "claim_window": {    "ends_at": "2019-08-24T14:15:22Z",    "starts_at": "2019-08-24T14:15:22Z"  },  "created_at": "2019-08-24T14:15:22Z",  "created_by": "string",  "description": "string",  "geo_fence": {    "countries": [      "string"    ],    "mode": "allow"  },  "name": "string",  "quarantine_reason": "string",  "requested_count": 0,  "reward_payload": null,  "status": "draft",  "stored_value": {    "enabled": true,    "initial_value": 0,    "partial_redemption": true  },  "total_redemptions": 0,  "updated_at": "2019-08-24T14:15:22Z"}

POST/api/v1/promo-codes/lock

Create_lock

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

code*string

The raw promo code to lock.

ttl_seconds*integer

Lock lifetime in seconds.

Formatint64

Range0 <= value

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/promo-codes/lock" \  -H "Content-Type: application/json" \  -d '{    "code": "string",    "ttl_seconds": 0  }'

{  "commit_token": "string",  "expires_at": "2019-08-24T14:15:22Z",  "lock_id": "string",  "status": "rejected"}

POST/api/v1/promo-codes/locks/{lock_id}/commit

Commit_lock

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

lock_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

commit_token*string

Commit token returned when the lock was created.

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/promo-codes/locks/string/commit" \  -H "Content-Type: application/json" \  -d '{    "commit_token": "string"  }'

{  "lock_id": "string",  "redemption_id": "string",  "reward_payload": null,  "status": "rejected"}

POST/api/v1/promo-codes/locks/{lock_id}/release

Release_lock

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

lock_id*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/promo-codes/locks/string/release"

{  "lock_id": "string",  "status": "rejected"}

POST/api/v1/promo-codes/redeem

Redeem

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

campaign_id?|

Optional campaign attribution id.

code*string

The raw promo code to redeem.

geo?null|

idempotency_key?|

Idempotency key ensuring the redemption is processed at most once.

on_behalf_of?|

Optional user to redeem on behalf of (requires admin privileges).

referrer_id?|

Optional referrer attribution id.

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/promo-codes/redeem" \  -H "Content-Type: application/json" \  -d '{    "code": "string"  }'

{  "redemption_id": "string",  "remaining_value": 0,  "reward_payload": null,  "status": "rejected"}

POST/api/v1/promo-codes/stored-value/redeem

Redeem_stored_value

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

amount*integer

Amount to debit from the stored-value balance.

Formatint64

code*string

The raw promo code to debit.

geo?null|

idempotency_key?|

Idempotency key ensuring the debit is processed at most once.

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/promo-codes/stored-value/redeem" \  -H "Content-Type: application/json" \  -d '{    "amount": 0,    "code": "string"  }'

{  "redemption_id": "string",  "remaining_value": 0,  "reward_payload": null,  "status": "rejected"}

Promo Code

200application/json

400

202application/json

400

403

200application/json

404

200application/json

403

404

200application/json

403

404

200application/json

403

404

200application/json

403

404

200application/json

400

403

404

200application/json

400

403

404

200application/json

409

200application/json

400

403

404

200application/json

403

404

200application/json

400

403

409

200application/json

400

409

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`