Apply a voucher

POST

/api/v3/carts/:cartId/vouchers

POST

/api/v3/carts/:cartId/vouchers

curl -X POST https://stg.ttix.io/api/v3/carts/6aac14d3-5826-4da8-98b6-9e68c28629d6/vouchers \
     -H "X-TT-Platform: android" \
     -H "X-TT-Retailer: YOUR_RETAILER_ID" \
     -H "X-TT-API-Key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "code": "SUMMER20"
}'

{
  "data": {
    "id": "6aac14d3-5826-4da8-98b6-9e68c28629d6",
    "expiresAt": "2026-03-15T19:40:00Z",
    "expiresInSeconds": 300,
    "items": [
      {
        "id": "Qm9va2luZ3Mx",
        "event": {
          "id": "123",
          "name": "Hamilton"
        },
        "occurrence": {
          "id": "456",
          "startsAt": "2026-03-15T19:30:00-04:00",
          "doorsOpen": {
            "at": "2026-03-15T19:00:00-04:00",
            "description": "Doors open 30 minutes before the performance."
          },
          "notices": [
            {
              "name": "Audio-described performance",
              "description": "Live audio description for visually impaired patrons."
            }
          ]
        },
        "venue": {
          "id": "UmljaGFyZCBSb2RnZXJzIFRoZWF0cmU",
          "name": "Richard Rodgers Theatre",
          "address": {
            "line1": "226 W 46th St",
            "line2": "Suite 200",
            "city": "New York",
            "state": "NY",
            "postalCode": "10036",
            "country": "US",
            "latitude": 40.759,
            "longitude": -73.9845
          },
          "timezone": "America/New_York"
        },
        "inventoryVariant": {
          "_type": "AssignedSeat",
          "attributes": [
            {
              "name": "Limited Legroom",
              "category": "NEGATIVE",
              "description": "Seats in this row have reduced legroom due to a safety barrier."
            }
          ],
          "id": "ORCHESTRA-A-101",
          "name": "Orchestra A 101",
          "row": "A",
          "seat": "101",
          "section": "Orchestra",
          "description": "Closest to the stage",
          "entrance": "Door 4",
          "extendedDescription": "Includes a complimentary drink. **Over 18s only.**",
          "images": [
            {
              "url": "https://example.com/seat-views/orchestra-a-101-center.jpg"
            }
          ]
        },
        "priceOption": {
          "category": {
            "name": "Adult",
            "id": "4471",
            "description": "Ages 3-12"
          },
          "sellPrice": {
            "amount": 18500,
            "currency": "USD"
          },
          "id": "eyJwcm92aWRlckNvZGUiOiJGVUxMUFJJQ0UiLCJob2xkQ29kZSI6IjE1NzM5In0",
          "constraints": {
            "requiresCategory": [
              "string"
            ]
          },
          "listPrice": {
            "amount": 18500,
            "currency": "USD"
          },
          "discountPercentage": 30,
          "discountAmount": {
            "amount": 18500,
            "currency": "USD"
          },
          "fees": [
            {
              "type": "SERVICE_FEE",
              "value": {
                "amount": 18500,
                "currency": "USD"
              }
            }
          ],
          "maxQuantityPerOrder": 4,
          "promotion": {
            "id": "promo-opening-week",
            "name": "Opening Week Special",
            "description": "40% off Orchestra seats for opening week performances."
          },
          "isDefault": true
        },
        "quantity": 1,
        "delivery": {
          "method": {
            "name": "E-ticket"
          },
          "instructions": "Your e-tickets will be emailed to you before the performance."
        }
      }
    ],
    "receiptLines": [
      {
        "label": "Subtotal",
        "total": {
          "amount": 18500,
          "currency": "USD"
        },
        "sign": "positive",
        "_type": "SubtotalLine"
      }
    ],
    "total": {
      "amount": 18500,
      "currency": "USD"
    },
    "protection": {
      "id": "prot_001",
      "pricePerItem": {
        "amount": 18500,
        "currency": "USD"
      },
      "total": {
        "amount": 18500,
        "currency": "USD"
      },
      "status": "ELIGIBLE"
    },
    "options": {
      "currencies": [
        "USD",
        "GBP",
        "EUR"
      ],
      "paymentMethods": [
        {
          "method": "CARD",
          "gateway": "ADYEN",
          "merchantAccount": "EncoreTicketsOwnBrand"
        }
      ],
      "extras": [
        {
          "id": "v1_eyJwcm92aWRlcklkIjoxMDAwLCJzZWF0SWQiOiJPUkNIRVNUUkEtQS0xMDEifQ",
          "inventoryVariant": {
            "_type": "AssignedSeat",
            "attributes": [
              {
                "name": "Limited Legroom",
                "category": "NEGATIVE",
                "description": "Seats in this row have reduced legroom due to a safety barrier."
              }
            ],
            "id": "ORCHESTRA-A-101",
            "name": "Orchestra A 101",
            "row": "A",
            "seat": "101",
            "section": "Orchestra",
            "description": "Closest to the stage",
            "entrance": "Door 4",
            "extendedDescription": "Includes a complimentary drink. **Over 18s only.**",
            "images": [
              {
                "url": "https://example.com/seat-views/orchestra-a-101-center.jpg"
              }
            ]
          },
          "priceOptions": [
            {
              "category": {
                "name": "Adult",
                "id": "4471",
                "description": "Ages 3-12"
              },
              "sellPrice": {
                "amount": 18500,
                "currency": "USD"
              },
              "id": "eyJwcm92aWRlckNvZGUiOiJGVUxMUFJJQ0UiLCJob2xkQ29kZSI6IjE1NzM5In0",
              "constraints": {
                "requiresCategory": [
                  "string"
                ]
              },
              "listPrice": {
                "amount": 18500,
                "currency": "USD"
              },
              "discountPercentage": 30,
              "discountAmount": {
                "amount": 18500,
                "currency": "USD"
              },
              "fees": [
                {
                  "type": "SERVICE_FEE",
                  "value": {
                    "amount": 18500,
                    "currency": "USD"
                  }
                }
              ],
              "maxQuantityPerOrder": 4,
              "promotion": {
                "id": "promo-opening-week",
                "name": "Opening Week Special",
                "description": "40% off Orchestra seats for opening week performances."
              },
              "isDefault": true
            }
          ],
          "quantityAvailable": 1,
          "maxQuantityPerOrder": 6,
          "minQuantityPerOrder": 4,
          "selectionGroup": {
            "inventoryItemIds": [
              "v1_eyJwcm92aWRlcklkIjoxMDAwLCJzZWF0SWQiOiJPUkNIRVNUUkEtQS0xMDEifQ",
              "v1_eyJwcm92aWRlcklkIjoxMDAwLCJzZWF0SWQiOiJPUkNIRVNUUkEtQS0xMDIifQ"
            ]
          },
          "selectionBlocked": {
            "chainSize": 3
          },
          "requirements": {
            "occurrence": {
              "earliestStart": "2026-03-01T15:00:00Z",
              "latestStart": "2026-03-02T03:00:00Z"
            }
          }
        }
      ]
    },
    "voucher": {
      "code": "SUMMER20",
      "discount": {
        "amount": 18500,
        "currency": "USD"
      }
    },
    "totalTaxes": {
      "amount": 18500,
      "currency": "USD"
    }
  }
}

Applies a voucher code to the cart and returns the updated cart with the discount reflected in receiptLines and total. Codes limited to one customer or one use per customer need a logged-in customer or the email field.

Authentication

X-TT-API-Keystring

API Key authentication via header

Path parameters

cartIdstringRequiredformat: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"

Cart ID (UUID)

Request

This endpoint expects an object.

codestringRequired0-15 characters

The voucher code to apply, as entered by the customer.

emailstringOptionalformat: "^(?=[\u0000-\uD7FF\uE000-\uFFFF]*$)[^@\s]+@[^@\s]+\.[^@\s]+$"0-100 characters

Guest checkout email. Some voucher codes are limited to one customer or one use per customer; without a logged-in customer, that check needs this email. Used only to validate the code — never stored.

Response headers

X-RateLimit-Limitinteger

How many requests this API key may make for this retailer in the current window. Sent only when the request was counted against that limit. A response served from cache was not counted and repeats the value it was cached with.

X-RateLimit-Remaininginteger

How many requests this API key has left for this retailer in the current window. Sent only when the request was counted against that limit. A response served from cache was not counted and repeats the value it was cached with.

Response

Voucher applied; updated cart returned.

dataobject

Shopping cart containing held inventory cart items.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

410

Gone Error

429

Too Many Requests Error