Discounts

Mint, read and archive discount codes, with an expiry and an owner.

Discount codes over the API. The dashboard has always had them; this lets an app or a server mint one: a loyalty reward, a referral, a make-good. A minted code can carry two things a dashboard code never needed: an expires_at, after which it is refused everywhere a code is checked, and a customer_id, after which it works for that customer’s email only and is silently ignored for anyone else. Codes are never edited; archive and mint another. An app sees and archives only the codes it created; a merchant key sees them all. Scoped keys need discounts:read / discounts:write. The hosted pay page accepts ?discount=CODE on its URL and applies it on load.

Create a discount code

Mint a code. Omit code to have one generated (unambiguous letters and digits, e.g. 7KQ2-M4XR, or PREFIX-7KQ2-M4XR with prefix). usage_limit defaults to 1: a minted code is single-use unless you say otherwise. Fixed amounts are in cents. Requires discounts:write on scoped keys.

POSThttps://paysio.com/api/v1/discounts

Authorizations

Authorizationstringheaderrequired

Secret key (sk_*) or app access token. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Body

typestring

"percentage" (default) or "fixed"

valueintegerrequired

Percent off (1-100) for percentage; amount off in cents for fixed. A code that brings the total to zero completes checkout as a free order: no card is collected, and payment.completed fires with amount 0

currencystring

For fixed amounts. Defaults to USD

codestring

Your own code, 3-40 characters of letters, digits and hyphens. Omit to mint one. 409 if it exists

prefixstring

Up to 8 letters or digits prepended to a minted code

usage_limitinteger

How many times it may be used. Default 1. null for unlimited

expires_atinteger

Unix timestamp. Refused after this, at validation and at payment

max_quantityinteger

Units the code may discount in one order. Null (default) discounts every unit; set 1 for one free or discounted item

customer_idstring

Only this customer may use it, matched by email at checkout

product_idsstring[]

Restrict the code to these products. Omit for the whole cart

Example request — cURL

curl -X POST https://paysio.com/api/v1/discounts \
  -H "Authorization: Bearer sk_test_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
  "value": 0
}'

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/discounts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "value": 0
  }),
})
const data = await res.json()

Example response (200)

{
  "data": {
    "object": "discount",
    "id": "3f0c2a9e-1b7d-4e6a-8c2f-9d1e0b4a7c55",
    "code": "LP-7KQ2-M4XR",
    "type": "fixed",
    "value": 500,
    "currency": "USD",
    "duration": "once",
    "duration_cycles": null,
    "usage_limit": 1,
    "usage_count": 0,
    "product_scope": "all",
    "product_ids": [],
    "max_quantity": null,
    "customer_id": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
    "expires_at": 1738368000,
    "archived": false,
    "created": 1735689600
  }
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

List discount codes

Your codes, newest first. An app lists only the codes it minted. Filter by customer_id to find the codes issued to one buyer. Requires discounts:read on scoped keys.

GEThttps://paysio.com/api/v1/discounts

Authorizations

Authorizationstringheaderrequired

Any API key. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Query parameters

customer_idstring

Only codes issued to this customer

limitinteger

1-100, default 50

Example request — cURL

curl -X GET https://paysio.com/api/v1/discounts \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/discounts", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": [{ "object": "discount", "id": "3f0c2a9e-1b7d-4e6a-8c2f-9d1e0b4a7c55", "code": "LP-7KQ2-M4XR", "type": "fixed", "value": 500, "usage_limit": 1, "usage_count": 1, "expires_at": 1738368000, "archived": false, "created": 1735689600 }],
  "has_more": false
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Retrieve a discount code

One code, with its usage_count. A transaction that used a code carries its discountId and discountCode, so a redemption can be matched back here.

GEThttps://paysio.com/api/v1/discounts/:id

Authorizations

Authorizationstringheaderrequired

Any API key. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Example request — cURL

curl -X GET https://paysio.com/api/v1/discounts/:id \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/discounts/:id", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": { "object": "discount", "id": "3f0c2a9e-1b7d-4e6a-8c2f-9d1e0b4a7c55", "code": "LP-7KQ2-M4XR", "type": "fixed", "value": 500, "usage_limit": 1, "usage_count": 1, "expires_at": 1738368000, "archived": false, "created": 1735689600 }
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Archive a discount code

The code stops working at once. The record stays, because transactions point at it. Requires discounts:write on scoped keys.

DELETEhttps://paysio.com/api/v1/discounts/:id

Authorizations

Authorizationstringheaderrequired

Secret key (sk_*) or app access token. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Example request — cURL

curl -X DELETE https://paysio.com/api/v1/discounts/:id \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/discounts/:id", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "id": "3f0c2a9e-1b7d-4e6a-8c2f-9d1e0b4a7c55",
  "object": "discount",
  "archived": true
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}