Coupons API

API Endpoint

An API to fetch information about existing coupons.

Coupons API

Fetch a list of created coupons

GET /coupons
RequestsBasic seller levelBasic partner levelSpecific pageCoupons with modified time
  • Example Url /coupons
Headers
Content-Type: application/json
Accept: application/json
Responses200400401403
Headers
Content-Type: application/json
Body
[
  {
    "id": 1,
    "name": "My Coupon",
    "type": "Discount",
    "code": "my-code",
    "amount": 10,
    "amount_type": "percentage",
    "modified_time": 1719827944
  },
  {
    "id": 2,
    "name": "Reserved Coupon",
    "type": "Reserved",
    "code": "reserved-1",
    "modified_time": 1719827011
  }
]
Schema
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "id": {
                "type": "number"
            },
            "name": {
                "type": "string"
            },
            "type": {
                "type": "string"
            },
            "code": {
                "type": "string"
            },
            "amount": {
                "type": "number"
            },
            "amount_type" {
                "type": "string"
            },
            "modified_time": {
                "description": "Last time this coupon was modified",
                "format": "UNIX Timestamp",
                "type": "number"
            }
        }
    }
}
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "status": "400",
      "detail": [
        "Bad request"
      ]
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "status": "401",
      "detail": "Unauthorized"
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "status": "403",
      "detail": "Forbidden"
    }
  ]
}
  • Example Url /coupons?sellerId=1
Headers
Content-Type: application/json
Accept: application/json
Responses200400401403
Headers
Content-Type: application/json
Body
[
  {
    "id": 1,
    "name": "My Coupon",
    "type": "Discount",
    "code": "my-code",
    "amount": 10,
    "amount_type": "percentage",
    "modified_time": 1719827944
  },
  {
    "id": 2,
    "name": "Reserved Coupon",
    "type": "Reserved",
    "code": "reserved-1",
    "modified_time": 1719827011
  }
]
Schema
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "id": {
                "type": "number"
            },
            "name": {
                "type": "string"
            },
            "type": {
                "type": "string"
            },
            "code": {
                "type": "string"
            },
            "amount": {
                "type": "number"
            },
            "amount_type" {
                "type": "string"
            },
            "modified_time": {
                "description": "Last time this coupon was modified",
                "format": "UNIX Timestamp",
                "type": "number"
            }
        }
    }
}
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "status": "400",
      "detail": [
        "Bad request"
      ]
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "status": "401",
      "detail": "Unauthorized"
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "status": "403",
      "detail": "Forbidden"
    }
  ]
}
  • Example Url /coupons?sellerId=1&page=2
Headers
Content-Type: application/json
Accept: application/json
Responses200400401403
Headers
Content-Type: application/json
Body
[
  {
    "id": 1,
    "name": "My Coupon",
    "type": "Discount",
    "code": "my-code",
    "amount": 10,
    "amount_type": "percentage",
    "modified_time": 1719827944
  },
  {
    "id": 2,
    "name": "Reserved Coupon",
    "type": "Reserved",
    "code": "reserved-1",
    "modified_time": 1719827011
  }
]
Schema
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "id": {
                "type": "number"
            },
            "name": {
                "type": "string"
            },
            "type": {
                "type": "string"
            },
            "code": {
                "type": "string"
            },
            "amount": {
                "type": "number"
            },
            "amount_type" {
                "type": "string"
            },
            "modified_time": {
                "description": "Last time this coupon was modified",
                "format": "UNIX Timestamp",
                "type": "number"
            }
        }
    }
}
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "status": "400",
      "detail": [
        "Bad request"
      ]
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "status": "401",
      "detail": "Unauthorized"
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "status": "403",
      "detail": "Forbidden"
    }
  ]
}
  • Example Url /coupons?sellerId=1&modifiedSince=1714594526
Headers
Content-Type: application/json
Accept: application/json
Responses200400401403
Headers
Content-Type: application/json
Body
[
  {
    "id": 1,
    "name": "My Coupon",
    "type": "Discount",
    "code": "my-code",
    "amount": 10,
    "amount_type": "percentage",
    "modified_time": 1719827944
  },
  {
    "id": 2,
    "name": "Reserved Coupon",
    "type": "Reserved",
    "code": "reserved-1",
    "modified_time": 1719827011
  }
]
Schema
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "id": {
                "type": "number"
            },
            "name": {
                "type": "string"
            },
            "type": {
                "type": "string"
            },
            "code": {
                "type": "string"
            },
            "amount": {
                "type": "number"
            },
            "amount_type" {
                "type": "string"
            },
            "modified_time": {
                "description": "Last time this coupon was modified",
                "format": "UNIX Timestamp",
                "type": "number"
            }
        }
    }
}
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "status": "400",
      "detail": [
        "Bad request"
      ]
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "status": "401",
      "detail": "Unauthorized"
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "status": "403",
      "detail": "Forbidden"
    }
  ]
}

Fetch a list of created coupons
GET/coupons

Fetches created coupons visible to the user linked to your API token.

If your API token is seller level then the sellerId param is not required, it is inferred from the token.

Url Parameters

  • sellerId: (number, required if partner level) - The seller id to fetch coupons for.

  • page: (number) - The page number to fetch. 200 items are returned per page.

  • modifiedSince: (number) - The unix timestamp to fetch coupons modified since.

Coupons Assignment

POST /coupons-assignment
Requestsexample 1
Headers
Accept: application/vnd.api+json
Responses200400403
Headers
Content-Type: application/vnd.api+json
Body
{
  "success": true
}
Headers
Content-Type: application/vnd.api+json
Body
{
  "errors": [
    {
      "id": "Z5H9z2MthdCjh7A",
      "status": 400,
      "detail": "Only discount and comp coupons can be applied to bundles"
    }
  ]
}
Headers
Content-Type: application/vnd.api+json
Body
{
  "errors": [
    {
      "id": "s8H9z2MthdCf4fjs",
      "status": 403,
      "detail": "The user does not have permission to edit the offer"
    }
  ]
}

Coupons Assignment
POST/coupons-assignment

Assigns coupons based on the provided arguments.

Request Attributes

Property Type Notes
coupon_ids array Required. An array of coupon IDs to be assigned to the offer.
offer_type string Required. The type of offer, either individual or group.
start_date string Required. The start date of the offer in YYYY-MM-DD format.
end_date string Required. The end date of the offer in YYYY-MM-DD format.
limit integer Required. The limit on the number of times the offer can be used.
ticket_limit integer Optional. The limit on the number of tickets that can be purchased with the offer.
global boolean Optional. Whether the offer is global.
event_ids array Optional. An array of event IDs to which the offer applies.
price_level_ids array Optional. An array of price level IDs to which the offer applies.
bundle_ids array Optional. An array of bundle IDs to which the offer applies.
timezone string Optional. The timezone for the dates. Defaults to the server timezone.
date_filter string Optional. Blackout date filters.
taggable boolean Optional. Whether the offer is taggable.

Fetch coupon's details by id

GET /coupons/1
Responses200400401403
Headers
Content-Type: application/json
Body
{
  "id": 1,
  "name": "My Coupon",
  "type": "Discount",
  "code": "my-code",
  "amount": 10,
  "amount_type": "percentage",
  "modified_time": 1719827944
}
Schema
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "id": {
            "type": "number"
        },
        "name": {
            "type": "string"
        },
        "type": {
            "type": "string"
        },
        "code": {
            "type": "string"
        },
        "amount": {
            "type": "number"
        },
        "amount_type" {
            "type": "string"
        },
        "modified_time": {
            "description": "Last time this coupon was modified",
            "format": "UNIX Timestamp",
            "type": "number"
        },
        "offers": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "number"
                    },
                    "timezone": {
                        "type: "string"
                    },
                    "start_date": {
                        "type: "string"
                    },
                    "end_date": {
                        "type: "string"
                    },
                    "limit": {
                        "type: "number"
                    },
                    "ticket_limit": {
                        "type: "number"
                    },
                    "taggable": {
                        "type: "boolean"
                    },
                    "global": {
                        "type: "boolean"
                    },
                    "assignments": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "sellers": {
                                    "type": "array",
                                    "items": {
                                        "type": "number"
                                    }
                                },
                                "events": {
                                    "type": "array",
                                    "items": {
                                        "type": "number"
                                    }
                                },
                                "price_levels": {
                                    "type": "array",
                                    "items": {
                                        "type": "number"
                                    }
                                },
                                "bundles": {
                                    "type": "array",
                                    "items": {
                                        "type": "number"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "status": "400",
      "detail": [
        "Bad request"
      ]
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "status": "401",
      "detail": "Unauthorized"
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "errors": [
    {
      "status": "403",
      "detail": "Forbidden"
    }
  ]
}

Fetch coupon's details by id
GET/coupons/{couponId}

Fetches coupon’s details.

URI Parameters
HideShow
couponId
number (required) Example: 1

Validate Coupon

GET /coupon-validation?code=code&eventId=eventId&listingId=listingId&token=token
Responses200
Headers
Content-Type: application/json
Body
{
  "valid": true
}

Validate Coupon
GET/coupon-validation?code={code}&eventId={eventId}&listingId={listingId}&token={token}

Validates if a coupon is valid for a given event and listing

URI Parameters
HideShow
code
string (required) 

The coupon code to validate

eventId
number (required) 

The ID of the event the coupon is for

listingId
number (required) 

The ID of the listing the coupon is for

token
string (optional) 

The reservation token

Submit Coupon Code

Applies a coupon code to a reservation

POST /reservations/id/coupon-usage
Requestsexample 1
Headers
Content-Type: application/json
Reservation-Secret: (string)
Body
{
  "data": {
    "type": "coupon-usage",
    "attributes": {
      "coupons": [
        {
          "event_id": 241,
          "code": "50off",
          "amount": null,
          "coupon_type": null
        }
      ]
    }
  }
}
Responses200
Headers
Content-Type: application/json
Reservation-Secret: (string)
Body
{
  "data": [
    {
      "id": "22109478",
      "type": "coupon-usage",
      "attributes": {
        "event_id": 241,
        "code": "50off",
        "amount": 500,
        "coupon_type": 2,
        "reservation_id": "436",
        "coupon_name": "Test Discount Code",
        "ticket_limit": 10,
        "coupon_link_id": "14",
        "valid_reserve_price_level_ids": []
      },
      "relationships": [],
      "dependents": []
    }
  ]
}

Submit Coupon Code
POST/reservations/{id}/coupon-usage

Request Attributes

Property Type Notes
coupons collection A collection of coupon requests

Each coupon request should contain:

Property Type Required Notes
event_id number yes The integer ID of the event
code string yes the coupon code to be applied
amount number no
coupon_type number no

Response Attributes

Property Type Notes
coupons collection A collection of coupon usages

Each coupon usage should contain:

Property Type Notes
event_id number The integer ID of the event
code string The coupon code that was applied
amount number the discount amount (if applicable) in minor units
coupon_type number The type of coupon applied
reservation_id number The id of the reservation the coupon was applied to
coupon_name string The name of the coupon
ticket_limit number The number of tickets the coupon can be applied to
coupon_link_id number The id of the coupon link
valid_reserve_price_level_ids collection A collection of price levels a reserve coupon allows access to

Coupon Types:

Type Description
2 Discount
3 Presale
4 Reserve
7 Comp
8 Auto
10 Invite
11 Access
URI Parameters
HideShow
id
string (required) 

ID of the Reservation`

Generated by aglio on 14 Feb 2025