Cupons

Criar Cupom

POST/v1/coupons

Base URL Produção:https://api.validapay.com.br

Base URL Sandbox:https://sandbox.validapay.com.br

Autenticação

bearerAuthorizationstring · header · obrigatório

Envie no header:

Authorization: Bearer {{token}}

Cria um cupom de desconto com valor fixo ou percentual, limite de usos e período de validade.

Criar cupom

Scopes: coupons/write

Campo	Obrig.	Tipo	Descrição
`code`	✅	string	Código único (case-insensitive), max 50
`discountType`	✅	string	`PERCENTAGE` `FIXED`
`discountValue`	✅	number	> 0; ≤ 100 se PERCENTAGE
`maxCycles`	❌	number	Ciclos com desconto (null = infinito)
`maxRedemptions`	❌	number	Usos totais (null = ilimitado)
`minAmount`	❌	number	Valor mínimo p/ aplicar
`maxDiscount`	❌	number	Teto de desconto em reais
`validFrom`/`validUntil`	❌	string	ISO 8601
`productIds`	❌	string[]	Restringe a produtos
`firstTimeOnly`	❌	boolean	Só 1ª compra
`appliesTo`	❌	string	`RECURRING` `ONE_TIME` `ALL`

Body

application/json

Content-Type:application/json

{
  "code": "PROMO10",
  "name": "Desconto de 10%",
  "description": "Válido somente para novos clientes",
  "discountType": "PERCENTAGE",
  "discountValue": 10,
  "maxCycles": 3,
  "maxRedemptions": 100,
  "minAmount": 50.0,
  "maxDiscount": 30.0,
  "validFrom": "2024-01-01T00:00:00Z",
  "validUntil": "2024-12-31T23:59:59Z",
  "productIds": [
    "prod_xxx"
  ],
  "firstTimeOnly": true,
  "appliesTo": "RECURRING"
}

Schema

Field	Type	Required	Description
code	string	-	-
name	string	-	-
description	string	-	-
discountType	string	-	-
discountValue	number	-	-
maxCycles	number	-	-
maxRedemptions	number	-	-
minAmount	number	-	-
maxDiscount	number	-	-
validFrom	string	-	-
validUntil	string	-	-
productIds[1]	array	-	-
firstTimeOnly	boolean	-	-
appliesTo	string	-	-

Headers

Name	Type	Value	Required
Content-Type	-	application/json	Optional

← Anterior

Remover Cliente

Listar Cupons

const url = 'https://sandbox.validapay.com.br/v1/coupons';

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "code": "PROMO10",
  "name": "Desconto de 10%",
  "description": "Válido somente para novos clientes",
  "discountType": "PERCENTAGE",
  "discountValue": 10,
  "maxCycles": 3,
  "maxRedemptions": 100,
  "minAmount": 50.0,
  "maxDiscount": 30.0,
  "validFrom": "2024-01-01T00:00:00Z",
  "validUntil": "2024-12-31T23:59:59Z",
  "productIds": [
    "prod_xxx"
  ],
  "firstTimeOnly": true,
  "appliesTo": "RECURRING"
})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

201201

{
  "couponId": "cou_xxx",
  "code": "PROMO10",
  "status": "ACTIVE"
}

400400

{
  "code": "COUPON_CODE_DUPLICATE"
}

← Anterior

Remover Cliente

Listar Cupons