Coupons

Endpoints for managing discount coupons and benefits.

List Coupons

GET /api/coupons

Returns a paginated list of coupons with filtering options. Results are limited to a maximum of 100 coupons per request. Works with franchise and company integrations.

Use cases:

• Query issued coupons
• Generate usage reports
• Monitor expiring coupons

Query Parameters

Parameter	Type	Required	Description
date_start	string	Yes	Start date to filter by creation date (YYYY-MM-DD)
date_end	string	Yes	End date to filter by creation date (YYYY-MM-DD)
date_of_use_start	string	No	Start date to filter by usage date (YYYY-MM-DD)
date_of_use_end	string	No	End date to filter by usage date (YYYY-MM-DD)
expiration_date_start	string	No	Start date to filter by expiration date (YYYY-MM-DD)
expiration_date_end	string	No	End date to filter by expiration date (YYYY-MM-DD)
coupon_status	string	No	Coupon status: Used, Not Used, Expired, Expiring
limit	integer	Yes	Number of coupons per request (max 100)
offset	integer	Yes	Number of coupons to skip (min 1)
search	string	No	Search term for code or client information
order_column	string	Yes	Column for sorting (e.g., created_at)
order_type	string	Yes	Sort direction: ASC or DESC
module	string	Yes	Module context: premiado or falae

Request Example

curl -X GET "https://api-b2s.experienciab2s.com/api/coupons?date_start=2024-01-01&date_end=2024-12-31&limit=10&offset=1&order_column=created_at&order_type=DESC&module=falae" \
     -H "Authorization: Bearer YOUR_TOKEN"

Success Response (200)

{
  "limit": 10,
  "offset": 1,
  "total": 45,
  "coupons": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "code": "WELCOME2024",
      "status": true,
      "date_of_use": "2024-03-15",
      "expiration_date": "2024-12-31",
      "created_at": "2024-01-15T10:30:00.000Z",
      "bonus": {
        "id": "bonus-uuid",
        "name": "5% Cashback",
        "type": "answer"
      },
      "client": {
        "id": "client-uuid",
        "name": "John Smith",
        "email": "john@example.com",
        "phone": "(11) 99999-9999"
      }
    }
  ]
}

Available Bonus Types

Type	Description
answer	Survey response
birthday	Birthday
default	Default
create	Creation
fidelityProgram	Loyalty program
prizeDraw	Prize draw
marketing	Marketing
roulette	Roulette
winning_registration_roulette	Roulette winning registration
infinity	Infinity

---

Get Client Coupons

GET /api/coupons/clients/{company_id}

Returns a list of coupons linked to a specific client using phone, email, or CPF as search criteria. The company_id must be provided in the request path.

Use cases:

• Check client coupons during service
• Verify available benefits
• Validate coupon before redemption

Path Parameters

Parameter	Type	Required	Description
company_id	string	Yes	Company ID

Query Parameters

Parameter	Type	Required	Description
phone	string	No*	Phone in international E.164 format (e.g., 551199999999)
email	string	No*	Client email address
cpf	string	No*	Client CPF in 000.000.000-00 format

Note: At least one search parameter (phone, email, or cpf) must be provided.

Request Example

curl -X GET "https://api-b2s.experienciab2s.com/api/coupons/clients/103a525c-0ce3-4182-a504-aad595425233?email=client@example.com" \
     -H "Authorization: Bearer YOUR_TOKEN"

Success Response (200)

[
  {
    "id": "103a525c-0ce3-4182-a504-aad595425233",
    "status": true,
    "expiration_date": "2024-12-31",
    "date_of_use": "2024-05-10",
    "created_at": "2024-01-01T12:00:00.000Z",
    "code": "ABCDEF123",
    "bonus": {
      "name": "5% Cashback"
    }
  },
  {
    "id": "303a525c-0ce3-4182-a504-aad595425233",
    "status": false,
    "expiration_date": "2024-11-30",
    "date_of_use": null,
    "created_at": "2024-02-15",
    "code": "XYZ789",
    "bonus": {
      "name": "10% Cashback"
    }
  }
]

Response Structure

Field	Type	Description
id	string	Unique coupon ID
code	string	Coupon code
status	boolean	true = used, false = not used
expiration_date	string	Expiration date
date_of_use	string	Usage date (null if not used)
created_at	string	Creation date
bonus.name	string	Benefit name

Response Codes

Code	Description
200	Coupons found
400	Invalid parameters
401	Missing or invalid token
404	Client not found

---

Mark Coupon as Used

PATCH /api/coupons/status/{id}

Updates the coupon status, marking it as used. The system validates if the coupon exists, hasn't been used before, and isn't expired (expiration date must be more than 3 hours from current time).

Automatic validations:

• If the coupon exists
• If it hasn't been used before
• If it's still valid (at least 3 hours before expiration)

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Unique ID of the coupon to update

Request Example

curl -X PATCH "https://api-b2s.experienciab2s.com/api/coupons/status/abc123-coupon-id" \
     -H "Authorization: Bearer YOUR_TOKEN"

Success Response (204)

The coupon status was updated successfully. No content is returned in the response.

Error Responses (400)

{
  "status": "error",
  "message": "Coupon already used"
}

{
  "status": "error",
  "message": "Coupon expired"
}

Response Codes

Code	Description
204	Coupon updated successfully
400	Coupon already used or expired
401	Missing or invalid token
404	Coupon not found