SeatGeek Exchange Integration Reference
Note: This documention is under active development. We would love your feedback
as we continue to refine and improve it.
Please email checkout@seatgeek.com
with any questions, comments or concerns. Thanks!
Note: If you do not want SeatGeek to be the merchant of record for the checkout integration, please refer to the SeatGeek Checkout Web Service Reference
This document outlines the required API service endpoints for marketplaces integrating SeatGeek Checkout. For an overview of SeatGeek checkout see SeatGeek Checkout Technical Overview.
- API Interface
- Implementing Authentication
- Event Catalog and Listings
- Getting the Information Necessary to Render a Checkout Form
- Submitting a Purchase
- Getting the Information for a Purchase
- Purchase Ping
API Interface
A REST-style web service protocol is used to communicate with your server to
make purchases, retrieve and provide updates on purchases, and to fetch delivery information
for purchases. The endpoints always begin with the web service URL, as defined by
you, followed by the protocol version number. For example, a request for the latest
information about a listing with id 123456
might look like the following:
For all endpoints, HTTPS with a valid, signed certificate is required. To authenticate that requests are being sent by SeatGeek, please see Web Service Authentication below.
For all response types not specified, be sure to use the appropriate HTTP response code. For example, for unexpected errors, a response code in the 5xx range should be used.
If a request fails—for example, due to a network connectivity
issue—Checkout tries again several times after waiting a period of
time. Each time it tries again, it waits longer. If the request
continues to fail, it eventually gives up. To prevent duplicate purchases,
POSTs to /purchases
are not retried.
For POST requests, request data is passed as JSON-encoded data in the structures specified below. For GET requests, request data is passed in the query string.
For all endpoints, specify the application/json
MIME type for
responses that contain JSON data.
All endpoints in this document include a section detailing the errors that may be returned by the call. These errors must be accompanied by HTTP status code 400, and use the following JSON structure:
Field | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|
errors array |
|
All requests will include the X-SG-Transaction-Id
HTTP header. This header will contain
a transaction id originally generated in the SeatGeek Checkout clients and passed through
every user request, and in turn every API request. It's recommended that you log the value
of this header to aid in debugging.
Web Service Authentication
In order to authenticate that requests to the web service are being sent by SeatGeek, we provide an authentication code which is calculated using your SeatGeek API client secret. You should perform the same calculation in your web service and ensure the the authentication code matches.
The format of the Authorization
header is as follows:
Authorization: SG client_id:hmac_signature
The first part of the header, SG
, specifies that the SeatGeek
web service authentication scheme is being used. The second part of the header
containes your SeatGeek API client id concatenated to the authentication code
with a :
.
The authentication code can be calculated as such, where client_secret
is the SeatGeek API client secret that corresponds to the passed client id:
hmac_signature = BASE64( HMAC_SHA1( client_secret, UPPERCASE( method ) + "\n" + path + "\n" + body ) )
Explanation of fields
Field | Description |
---|---|
client_id | Provided to you by SeatGeek. If you are unsure of your client credentials, contact us at checkout@seatgeek.com. |
client_secret |
Provided to you by SeatGeek along with your client_id .
|
method |
The request method. Typically GET or POST .
|
path |
The full path of the URL being requested. In other words if the
URL being requested is https://example-market.com/foo/v1/purchases?param=1 ,
the path would be /foo/v1/purchases .
|
body | The raw body of the request. |
Getting the Information Necessary to Render a Checkout Form
For this SeatGeek will use the listings endpoint detailed in the Event Catalog and Listings docs with the listing_id parameter.
Submitting a Purchase
POST /purchases
Request Parameters
Field | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
product object |
product information for the purchase
|
||||||||||||||||
user object |
optional - user information for the purchase
|
||||||||||||||||
ref_idstring | a SeatGeek-specified identifier to be stored with your record of the purchase and included in affiliate reporting |
Getting the Latest Information for a Purchase
GET /purchases/{id}
Request Parameters
Field | Description |
---|---|
idstring | Your ID for the purchase |
Response Parameters
Field | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|
idstring | Your ID for the purchase | ||||||||
statusobject | The status of the order. See Status Object | ||||||||
product object |
product information for the purchase
|
||||||||
delivery_method object | delivery method information for the purchase, see Delivery Method Data | ||||||||
fulfillment object | Fulfillment information for the purchase, see Fulfillment Data | ||||||||
market_specific_fields object | optional - additional data elements specific to a particular market | ||||||||
ref_idstring | optional - a SeatGeek-specified identifier to be stored with your record of the purchase and included in affiliate reporting |
Status Object
Field | Description |
---|---|
statusstring | One of: pending , confirmed , rejected , or exception
|
status_messagestring | Description of the status. See Status Messages |
status_codeint | A unique code to identify the status and status_message pair |
Status Messages
Status messages allow SeatGeek to provide users with detailed information about their order. Integrations should return a message indicating the status of the order along with a status_code
uniquely identifying the status
and status_message
pair (codes are defined by the integrating partner).
Note: The best integrations will include a full list of status objects as status_history.
Each integration will have an individualized set of status messages. The following is the suggested minimum set of messages that should be returned with each status:
pending
- Pending confirmation
- Manual review
confirmed
- Order Confirmation Email Sent
- Tickets shipped (hard tickets)
- Tickets fulfilled - delivered to door
- Tickets fulfilled - email
- Replacement tickets offered - accepted
cancelled
- Fraud - system
- Fraud - manual review
- Tickets not available - listing no longer available
- Tickets not available - broker denies
- Tickets not available - broker did not respond
- Technical issue
- Event cancelled
- SeatGeek error
- Customer denied entry
- Order Confirmation Email bounced
- Fulfillment Email bounced
- Ticket shipping failed
- Replacement tickets offered - rejected
Fulfillment Data
Field | Description | ||||||
---|---|---|---|---|---|---|---|
typestring |
the type of fulfillment
|
||||||
dataobject | the data associated with the specified fulfilment type. See related data structures below. |
Shipping Fulfillment Data
Field | Description |
---|---|
carrierstring | Must be exactly one of "FedEx" or "UPS". If you offer additional carriers, please email checkout@seatgeek.com. |
tracking_numberstring | The exact tracking number returned from the carrier |
Download Fulfillment Data
Field | Description |
---|---|
urlstring |
Errors
Code | Message |
---|---|
40040 | Invalid purchase id |
Purchase Ping
POST /markets/purchases/{ORDER_ID}/update?ref_id={REF_ID}
This endpoint should be hit after every successful purchase and every time the order status changes.
Request Parameters
Field | Description |
---|---|
order_idstring | The market order_id of the purchase |
ref_idint | The SeatGeek reference ID submitted with the purchase |
Response Parameters
Field | Description |
---|---|
order_idstring | The market order_id of the purchase |