Redeem a coupon code for a profile

Redeems a coupon within the key’s project for a given profile. Idempotent per (profileId, couponId) unless an explicit idempotencyKey is supplied. Returns the granted benefits from the coupon pool.

Auth: X-API-Key with scope coupon:redeem (x-required-scope: coupon:redeem). projectId in the body must match the key’s project.

Rate limit: 30 req/min per (projectId, IP) — over → 429.

Authorizations

ApiKeyAuth

Request Body^required

application/json

object

projectId

required

Must match the API key’s project.

string

code

required

Coupon code to redeem.

string

profileId

required

User/profile redeeming the coupon.

string

idempotencyKey

Optional. Defaults to <profileId>:<couponId> when omitted.

string

context

Optional free-form redemption context.

object

key

additional properties

any

Example

1
{
2
  "projectId": "prj_123",
3
  "code": "SAVE10",
4
  "profileId": "uid_456",
5
  "idempotencyKey": "order-789"
6
}

Responses

200

Redemption accepted (pending settlement).

application/json

object

redemptionId

required

string

status

required

string

benefits

required

Benefits defined on the coupon pool (empty object if none).

object

key

additional properties

any

400

Invalid JSON or missing required fields.

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Examples

1
{
2
  "error": "invalid_json"
3
}

1
{
2
  "error": "missing_required_fields"
3
}

401

Missing/invalid API key.

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Example^generated

1
{
2
  "error": "example",
3
  "retryAfter": 1,
4
  "message": "example",
5
  "affectedIndices": [
6
    1
7
  ]
8
}

403

API key lacks the coupon:redeem scope.

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Example^generated

1
{
2
  "error": "example",
3
  "retryAfter": 1,
4
  "message": "example",
5
  "affectedIndices": [
6
    1
7
  ]
8
}

404

Coupon not found, or cross-tenant (same shape to prevent enumeration).

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Example

1
{
2
  "error": "not_found"
3
}

409

Coupon not redeemable.

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Examples

1
{
2
  "error": "already_redeemed"
3
}

1
{
2
  "error": "expired"
3
}

1
{
2
  "error": "revoked"
3
}

1
{
2
  "error": "pool_not_ready"
3
}

429

Rate limit exceeded (30/min per project+IP).

application/json

object

error

required

Human-readable error message.

string

retryAfter

Seconds to wait before retrying (present on 429/503).

integer

message

string

affectedIndices

Array<integer>

Example

1
{
2
  "error": "rate_limited"
3
}

POST

/api/v1/coupons/redeem

1
curl --request POST \
2
  --url https://api.retidal.com/api/v1/coupons/redeem \
3
  --header 'Content-Type: application/json' \
4
  --header 'X-API-Key: <YOUR_API_KEY>' \
5
  --data '{
6
  "projectId": "prj_123",
7
  "code": "SAVE10",
8
  "profileId": "uid_456",
9
  "idempotencyKey": "order-789"
10
}'

1
const url = 'https://api.retidal.com/api/v1/coupons/redeem';
2
const options = {
3
  method: 'POST',
4
  headers: {'X-API-Key': '<YOUR_API_KEY>', 'Content-Type': 'application/json'},
5
  body: '{"projectId":"prj_123","code":"SAVE10","profileId":"uid_456","idempotencyKey":"order-789"}'
6
};
7

8
try {
9
  const response = await fetch(url, options);
10
  const data = await response.json();
11
  console.log(data);
12
} catch (error) {
13
  console.error(error);
14
}

1
import requests
2

3
url = "https://api.retidal.com/api/v1/coupons/redeem"
4

5
payload = {
6
    "projectId": "prj_123",
7
    "code": "SAVE10",
8
    "profileId": "uid_456",
9
    "idempotencyKey": "order-789"
10
}
11
headers = {
12
    "X-API-Key": "<YOUR_API_KEY>",
13
    "Content-Type": "application/json"
14
}
15

16
response = requests.post(url, json=payload, headers=headers)
17

18
print(response.json())

1
import httpx
2
import json
3

4
url = "https://api.retidal.com/api/v1/coupons/redeem"
5

6
headers = {"X-API-Key": "<YOUR_API_KEY>"}
7

8
payload = json.loads("{\n  \"projectId\": \"prj_123\",\n  \"code\": \"SAVE10\",\n  \"profileId\": \"uid_456\",\n  \"idempotencyKey\": \"order-789\"\n}")
9

10
response = httpx.post(url, headers=headers, json=payload)
11

12
print(response.json())

1
package main
2

3
import (
4
  "fmt"
5
  "strings"
6
  "net/http"
7
  "io"
8
)
9

10
func main() {
11

12
  url := "https://api.retidal.com/api/v1/coupons/redeem"
13

14
  payload := strings.NewReader("{\n  \"projectId\": \"prj_123\",\n  \"code\": \"SAVE10\",\n  \"profileId\": \"uid_456\",\n  \"idempotencyKey\": \"order-789\"\n}")
15

16
  req, _ := http.NewRequest("POST", url, payload)
17

18
  req.Header.Add("X-API-Key", "<YOUR_API_KEY>")
19
  req.Header.Add("Content-Type", "application/json")
20

21
  res, _ := http.DefaultClient.Do(req)
22

23
  defer res.Body.Close()
24
  body, _ := io.ReadAll(res.Body)
25

26
  fmt.Println(res)
27
  fmt.Println(string(body))
28

29
}

200Redemption accepted (pending settlement).

1
{
2
  "redemptionId": "8f2c…",
3
  "status": "pending_settlement",
4
  "benefits": {
5
    "discountPercent": 10
6
  }
7
}

Redeem a coupon code for a profile

Authorizations

Request Bodyrequired

Example

Responses

200

400

Examples

401

Examplegenerated

403

Examplegenerated

404

Example

409

Examples

429

Example

Request Body^required

Example^generated

Example^generated