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

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
Field Description
code int machine-friendly error reason
message string error details for troubleshooting
user_message string optional - user-friendly error message that can displayed to SeatGeek users as a fallback

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
Field Description
event_idstring your ID for the event
listing_idstring your ID for the ticket listing
quantityint the quantity selected
totalfloat total wholesale price for the purchase
user object optional - user information for the purchase
Field Description
emailstring user email address
phonestring user phone number
ip_addressstring user IP address
locationobject user location - if available
Field Description
latfloat latitude
lonfloat longitude
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
Field Description
event_idstring your ID for the event
listing_idstring your ID for a listing
quantityint the quantity selected
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

confirmed

cancelled

Fulfillment Data

Field Description
typestring the type of fulfillment
Value Description
ship See "Shipping Fulfillment Data"
download See "Download Fulfillment Data"
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