Skip to content

Inventory API

Jump to bottom
milhowz edited this page Feb 20, 2013 · 21 revisions

##Object: TicketBlock

Field Type Description
ticket_id string your unique ID for this ticket
event_id string ScoreBig event ID
section string
row string
quantity string
start_seat string
end_seat string
odd_even bool indicates odd/even seating (e.g. "1,3,5" or "2,4,6")
electronic bool indicates whether or not eTickets are available for this TicketBlock
ga bool indicates whether or not the tickets are general admission
splits string indicates valid splits for this TicketBlock (up to 8)
face_value decimal face value of the ticket
price decimal your price for the ticket
notes string
in_hand_date date indicates when tickets will be available for delivery
expiration_datetime string indicates when tickets will be taken off ScoreBig

##Method: Get Inventory

This function returns a TicketBlock object for a specific ticket_id.

###URI

HTTP Method URI Description
GET /{:version}/tickets/{:ticket_id} returns TicketBlock identified by ticket_id
GET /{:version}/tickets?ticket_id={:ticket_id} returns TicketBlock identified by ticket_id
GET /{:version}/tickets?event_={:event_id} returns listing of TicketBlocks for specific Event

###Input Parameters

Parameter Type Occurrence Description
api_key guid required passed in the headers or query parameters
ticket_id string conditional your unique ID for this ticket. required if event_id is not provided.
event_id guid conditional the ScoreBig ID for an event. required if ticket_id is not provided.

###Example #1 - Single TicketBlock

#####Request

GET http://developer.api.scorebig.com/1/tickets/12345?api_key=abcde

GET http://developer.api.scorebig.com/1/tickets?api_key=abcde&ticket_id=12345

note: both URLs represent the same resource: a Ticket with ID '12345'

#####Response

{
    "type": "TicketBlock",
    "count": 1,
    "results": [
        {
            "ticket_id": "777",
            "event_id": "00000000-0000-0000-0000-000000000001",
            "section": "MEZ",
            "row": "A",
            "quantity": 4,
            "start_seat": "20",
            "end_seat": "23",
            "odd_even": false,
            "ga": false,
            "electronic": false,
            "splits": "1,2,3,4",
            "price": 21,
            "notes": null,
            "in_hand_date": null,
            "expiration_datetime": "1/1/2020 12:00:00 AM"
        }
    ]
}

###Example #2 - All TicketBlocks for an Event

#####Request

GET http://developer.api.scorebig.com/1/tickets?api_key=abcde&event_id=2234533

#####Response

{
    "type": "TicketBlock",
    "count": 3,
    "results": [
        {
            "ticket_id": "777",
            "event_id": "00000000-0000-0000-0000-000000000001",
            "section": "MEZ",
            "row": "A",
            "quantity": 4,
            "start_seat": "20",
            "end_seat": "23",
            "odd_even": false,
            "ga": false,
            "electronic": false,
            "splits": "1,2,3,4",
            "price": 21,
            "notes": null,
            "in_hand_date": null,
            "expiration_datetime": "1/1/2020 12:00:00 AM"
        },
        {
            "ticket_id": "888",
            "event_id": "00000000-0000-0000-0000-000000000001",
            "section": "MEZ",
            "row": "B",
            "quantity": 6,
            "start_seat": "20",
            "end_seat": "25",
            "odd_even": false,
            "ga": false,
            "electronic": false,
            "splits": "1,2,3,4,5,6",
            "price": 21,
            "notes": null,
            "in_hand_date": null,
            "expiration_datetime": "1/1/2020 12:00:00 AM"
        },
        {
            "ticket_id": "999",
            "event_id": "00000000-0000-0000-0000-000000000001",
            "section": "MEZ",
            "row": "C",
            "quantity": 8,
            "start_seat": "20",
            "end_seat": "27",
            "odd_even": false,
            "ga": false,
            "electronic": false,
            "splits": "1,2,3,4,5,6,7,8",
            "price": 21,
            "notes": null,
            "in_hand_date": null,
            "expiration_datetime": "1/1/2020 12:00:00 AM"
        }
    ]
}

##Method: Insert/Update Inventory

This method allows you to insert or update inventory on ScoreBig.com.

Single or Bulk

There are 2 options for inserting/updating inventory: single or bulk. In single mode, the parameters are a JSON object representing a single ticket block. In bulk mode, the parameters are an array of JSON objects representing each ticket block.

Insert or Update

If a ticket, identified by ticket_id, already exists, then this method will update that existing ticket, using just the fields that were passed in the request. If a ticket does not currently exist, then this method will validate that you have supplied all the required fields before inserting it into our system.

Event Matching

One of the requirements is that the ticket is matched to an existing event in our system. If an event_id is provided, the system will verify that the event_id exists in our system. If there is no event_id, it will attempt to identify the event based on the event_date_time and the venue. If not suitable match is found based on the information given, then an error will be returned in the response.

This is not a differencing system, so new blocks will be added and existing blocks will be updated. If you delete a block on your side, please make sure to call the Delete Inventory method to remove it from our system so we don't sell it. Merely excluding it from a future import will not remove it from our system.

###URI

HTTP Method URI Description
PUT /{:version}/tickets/{:ticket_id} inserts or updates a TicketBlock identified by ticket_id
POST /{:version}/tickets bulk inserts or updates multiple TicketBlocks

###Input Parameters

Parameter Type Occurrence Description
api_key guid required passed in the headers or query parameters
ticket_id string required your unique ID for this ticket.
event_id guid optional the ScoreBig ID for an event. use this for improved performance.
event_date_time string required Local event date time, in the format of MM-dd-yyyy hh:mm zz
venue string required Venue name. Please use current name of the venue
venue_address string optional Can improve event matching if provided
venue_city string optional Can improve event matching if provided
venue_state string optional Can improve event matching if provided
section string required
row string required
quantity int required
start_seat string required
end_seat string required
odd_even bool optional Specifies if seats are odd/even (e.g. 1,3,5 or 2,4,6). default is FALSE
splits string optional Comma-separated list of valid splits, i.e. 2,3,4,6,8. Max split is 8.
price decimal required Your price for the ticket
electronic bool optional Whether or not e-tickets are available. default is FALSE
in_hand_date string optional The date the listing can be shipped
notes string optional Any notes or comments associated with this ticket

NOTE: for update requests, only ticket_id is required

###Example #1 - Insert Single TicketBlock

####Request (json)

PUT http://developer.api.scorebig.com/1/tickets/222

Content-Type: application/json; charset=utf-8

{
    "ticket_id": "222",
    "event_id": "00000000-0000-0000-0000-000000000001",
    "section": "MEZ",
    "row": "B",
    "quantity": 4,
    "start_seat": "20",
    "end_seat": "23",
    "odd_even": false,
    "price": "21"
}

####Request (alternate)

PUT http://developer.api.scorebig.com/1/tickets/222

Content-Type: application/x-www-form-urlencoded

event_id=00000000-0000-0000-0000-000000000001&section=MEZ&row=B&quantity=4&start_seat=20&end_seat=23&odd_even=false&price=21

####Response

{
    "type" : "TicketResult",
    "count" : 1,
    "results" : [{
            "ticket_id" : "222",
            "success" : true,
            "message" : "New ticket added to queue."
        }
    ]
}

###Example #2 - Update Single TicketBlock

####Request (json)

PUT http://developer.api.scorebig.com/1/tickets/222

Content-Type: application/json; charset=utf-8

{
    "ticket_id": "222",
    "quantity": 2,
    "start_seat": "20",
    "end_seat": "21",
    "price": "16"
}

####Request (alternate)

PUT http://developer.api.scorebig.com/1/tickets/222

Content-Type: application/x-www-form-urlencoded

quantity=2&start_seat=20&end_seat=21&price=16

####Response

{
    "type" : "TicketResult",
    "count" : 1,
    "results" : [{
            "ticket_id" : "222",
            "success" : true,
            "message" : "Ticket update added to queue."
        }
    ]
}

###Example #3 - Bulk Insert Multiple TicketBlocks

####Request

POST http://developer.api.scorebig.com/1/tickets

Content-Type: application/json; charset=utf-8

{
    "tickets": [
        {
            "ticket_id": "777",
            "event_id": "00000000-0000-0000-0000-000000000001",
            "section": "MEZ",
            "row": "A",
            "quantity": 4,
            "start_seat": "20",
            "end_seat": "23",
            "ga": false,
            "odd_even": false,
            "price": "21"
        },
        {
            "ticket_id": "666",
            "event_id": "00000000-0000-0000-0000-000000000001",
            "section": "MEZ",
            "row": "B",
            "quantity": 6,
            "start_seat": "20",
            "end_seat": "25",
            "ga": false,
            "odd_even": false,
            "price": "21"
        },
        {
            "ticket_id": "777",
            "event_id": "00000000-0000-0000-0000-000000000001",
            "section": "MEZ",
            "row": "C",
            "quantity": 8,
            "start_seat": "20",
            "end_seat": "27",
            "ga": false,
            "odd_even": false,
            "price": "21"
        }
    ]
}

####Response

The response will be a list results, one for each TicketBlock, that details what happened to each block.

{
    "type" : "TicketResult",
    "count" : 3,
    "results" : [{
            "ticket_id" : "777",
            "success" : true,
            "message" : "New ticket added to queue."
        }, {
            "ticket_id" : "666",
            "success" : true,
            "message" : "New ticket added to queue."
        }, {
            "ticket_id" : "555",
            "success" : false,
            "message" : "More than one event was detected.  Try using an explicit Event ID in your request."
        }
    ]
}

##Method: Delete Inventory

This function will take a list of ticketblock ids and remove them from our system immediately.

###URI

HTTP Method URI Description
DELETE /{:version}/tickets/{:ticket_id} deletes TicketBlock identified by ticket_id
POST /{:version}/tickets/delete deletes all TicketBlocks identified by list of ticket_id

###Input Parameters

Parameter Type Occurrence Description
api_key guid required passed in the headers or query parameters
ticket_id string required single ticket_id or list of ticket_ids to be deleted.

###Example #1 - Delete Single Ticket

####Request

DELETE http://developer.api.scorebig.com/1/tickets/222

####Response

The response will be a message indicating the results of the delete operation.

{
    "type" : "Result",
    "count" : 1,
    "results" : ["Successfully deleted 1 of 1 ticket block(s)."]
}

###Example #2 - Bulk Delete Tickets

####Request

POST http://developer.api.scorebig.com/1/tickets/delete

Content-Type: application/json; charset=utf-8

{
    "ticket_id": [
        "777",
        "888"
    ]
}

####Response

The response will be a message indicating the results of the delete operation.

{
    "type" : "Result",
    "count" : 1,
    "results" : ["Successfully deleted 2 of 2 ticket block(s)."]
}

Clone this wiki locally