Processing Ticket Evolution Orders via API

Helpful tools

API Documentation: https://ticketevolution.atlassian.net/wiki/display/API/API+Documentation
API Demo: http://api-demo.ticketevolution.com/
PHP Library: https://github.com/ticketevolution/ticketevolution-php
Ruby Library: https://github.com/ticketevolution/ticketevolution-ruby

Create a User for Your Order Processor

Creating a separate user allows you to accurately see who has done what in our system. This applies to humans as well, please make sure each employee who needs access to our system has their own user account.

Follow these simple instructions to make a new user.

Establish API Credentials for Your Order Processor

We’ve also got simple instructions for creating API Credentials. If you already have API credentials for your website, please create an additional set just for order processing and label them accordingly.

Use the API to Retrieve a List of Orders With a `state` of `pending` and a `type` of `Order`

You can retrieve all your orders from the API, but for the purpose of automatically processing orders you want to filter to only ones with a state of pending.

curl -H 'X-Token: FsxRk6qxJgVn6qzsgPQznyvVNykPwd22' \
     -H 'X-Signature: WGiennHhZLefDmeUyAfvamiGkjEK77PXjMyyNxkdVswf' \
     -H 'Accept: application/json' \
     --url 'https://api.ticketevolution.com/v9/orders?state=pending&type=Order'

The result of that all will be an array of orders, even if there is only one.

You will want to loop through that list of orders processing each one. Each order will also have an array named items (even if there is only one). Each item will be a set of tickets identified by the remote_id which you provided to us in your upload as the unique identifier for that set of tickets, usually in a column named TicketID.

NOTE: Ticket Evolution is unique in that a single order may contain multiple ticket groups. Do not accept the order if you cannot supply every ticket group requested.
Contact customer support if you can only accept a portion of the order.

Because of this you will also need to loop through the items array as well. For each item you need to confirm in your system the following:

You can supply the requested quantity for all of the ticket groups
The price supplied is acceptable to you
If we are expecting you to upload PDF(s) for this item the boolean eticket_delivery property will be true or (1).

A pseudo-code example of what you probably want to do

Code Block

$orders = get_pending_orders_from_api();
foreach ($orders as $order) {
    $can_accept_order = true;
    foreach ($order->items as $item) {
        $tickets_are_available = check_our_inventory_for_availability($item->ticket_group->remote_id, $quantity);
        if (!$tickets_are_available) {
            $can_accept_order = false;
        }
    }
    if ($can_accept_order) {
        accept_order_with_tevo($order->id);
    } else {
        notify_someone_we_cannot_confirm_tevo_order();
    }
}

Differentiating Order Types

Differentiating based on buyer type

All orders have a buyer object and each buyer object has a property named type which can be used to identify if this is an order from a Ticket Evolution Partner or another broker or from one of your clients such as through your Ticket Evolution API-powered website (one you built using our API, one of our Carbon stores or even an ATBS provided site).

Partner/Broker orders will have a buyer->type of Office
Client orders either from your Ticket Evolution API-powered website or from the Core POS will have a buyer->type of Client

Differentiating based on payment type

All orders have a payments object detailing one or more payments associated with the order. Each payments object has a property named type which can be used to identify how that particular payment was made. Available types can be found in the Payments / Create documentation.

Differentiating orders for speculation tickets

All orders have a boolean spec property and if it is set to true that order contains one or more items that are speculation ticket groups

Table of Contents

Getting Notified of New Orders

There are multiple ways to know about new TEvo orders and they should all be used together.

Order Integration

Order Integration provides the best experience for buyers because it allows them to know immediately that the tickets they are purchasing have been secured.

With Order Integration at the time an order is being placed our servers will make an API request to your servers to verify the inventory is available and request a hold for a specified quantity of a ticket group. After receiving a successful hold response we will make an invoice request to tell you a TEvo order has been created and you should invoice those tickets to us. In rare cases of an issue on our side you may receive a hold release instead of an invoice request.

If we do not receive a successful hold response the purchaser will be alerted and no order will be created by TEvo.

Info
Not all buyers buyers purchase via Order Integration so even if you support Order Integration you should support Webhooks as well.

Learn more at Processing Orders via Order Integration.

Webhooks

Webhooks are the fastest and least resource intensive way for you to know when a new order has been placed for your tickets. When a buyer submits an order to TEvo we will send a webhook to a URL you provide to alert you that a new order for your tickets has been created.

We also provide webhooks for many other operations including ones where you are the buyer.

Learn more at Processing Orders via Webhooks.

Polling

Polling our API for new orders is recommended only as a fail-safe to webhooks.

Learn more at Processing Orders via Polling.

Differentiating Order Types

Sales to TEvo

Sales where TEvo is the buyer are the most common type of sales you can expect to see. These sales can be identified by examining the order in the body for buyer.type=Office & buyer.id=6.

Sales to a Client

If a seller has a website powered by the TEvo API or they utilize Core to create sales to Clients then any sale where tickets are being sold their client can be identified by examining the order in the body for buyer.type=Client.

When invoicing these sales you should search the Point of Sale for a customer matching the Client. If no matching customer is found then one should be created using the buyer information before creating an invoice selling those tickets to the client.

Note
Be aware of the `fraud_check_status` of sales to a Client

If a sale to a Client has fraud_check_status of null then that seller does not use Riskified.

If a sale to a Client has fraud_check_status of pending then we are awaiting an approval or detail from Riskified. Riskified will send TEvo periodic updates, each one of which will trigger a webhook with recipient=seller & event_type=fraud_response_received. The sale should not be accepted or invoiced until one is received where the fraud_check_status=approved.

Accepting an Order

When you accept an order you are obligating your company to provide all of committing to providing the requested tickets. You cannot accept just a portion of an order that has multiple items.

Info

Before accepting an order you need to confirm in your system:

You can supply the requested quantity for all of the ticket groups
The price supplied is acceptable to you

In the example below be sure to replace :{order_id} in the URL with the id of the order (not the id of the item). Also, use the id of the user User that was given to you created earlier as the reviewer_id. This way you will know that this order was accepted by your super-cool order processing robot.

Code Block
curl -H 'X-Token: FsxRk6qxJgVn6qzsgPQznyvVNykPwd22' \ -H 'X-Signature: RFajHc97ooCUqQUAPPXVAmrapqVnunmcLFZP4a8ZVHJs' \

...


     -H 'Accept: application/json' \

...

-d '{"reviewer_id":

...

{reviewer_id}}' \

...

--url 'https://api.ticketevolution.com/v9/orders/{order_id}/accept'

...

Fulfilling Orders

Mobile Tickets

Learn more at Automate Mobile Transfers.

Etickets (Print at Home or QR codes)

If you have confirmed—either manually or via the API—an order where one or more of the items has a value of true for eticket_delivery then you can deliver those tickets via the API.

...

.

...

With our API you can either deliver etickets either as one file per page or as one single file that includes all and only all of the requested tickets. > If you have a PDF file that has more tickets than you need to deliver you will need to split that file first or manually upload those tickets and choose the pages to deliver.

Delivering Separate Files for Each Page

Use the Items / Add Etickets endpoint to upload individual files for each ticket. You can send all the files in an array in a single POST or you may POST them one at a time, or a combination of the two.

In the example below the item_id is the property named id from the item within the order, not the order_item_id.

Code Block

language	bash

curl -H 'X-Token: FsxRk6qxJgVn6qzsgPQznyvVNykPwd22' \
     -H 'X-Signature: Lyu2RxCtxYNZvJJXwDQbquoCcHB3gchHJWpaKkB6KBjk' \

...


     -H 'Accept: application/json' \

...


     --url 'https://api.ticketevolution.com/v9/orders/{order_id}/items/{item_id}/add_etickets'

...


     -d '{"files":["<base64-encoded file>","<another base64-encoded file>"]}'

Once you have added all of the files, simple let us know that you have completed it by POSTing to the Items / Finalize Etickets endpoint.

Code Block

language	bash

curl -H 'X-Token: FsxRk6qxJgVn6qzsgPQznyvVNykPwd22' \
     -H 'X-Signature: nMNnzD2zauXFNgNoDwWBKwUg2TbJKZKLEwRcsmigdjkA' \
     -H 'Accept: application/json' \

...


     -url 'https://api.ticketevolution.com/v9/orders/{order_id}/items/{item_id}/finalize_etickets' \
     -d '{"keep_pages":[1,2,3,4]}'

If you need to, you can “reset” and wipe out all uploaded files using Items / Remove Etickets any time before you Finalize.

Code Block

language	bash

curl -H 'X-Token: FsxRk6qxJgVn6qzsgPQznyvVNykPwd22' \
     -H 'X-Signature: 2QGKdX7No4HFzDEkApbZfHiLnkFsHbnTKYWGiennHhZL' \

...


     -H 'Accept: application/json' \

...


     --url 'https://api.ticketevolution.com/v9/orders/{order_id}/items/{item_id}/remove_etickets'

Delivering All Tickets in a Single File

Use the Orders / Deliver Etickets endpoint to upload a single base64 encoded PDF file that has all of the tickets.

In the example below the item_id value comes from the property named order_item_id from id from the item within the order, not the id.

Code Block

language	bash

curl -H 'X-Token: FsxRk6qxJgVn6qzsgPQznyvVNykPwd22' \
     -H 'X-Signature: 2QGKdX7No4HFzDEkApbZfHiLnkFsHbnTKYWGiennHhZL' \

...


     -H 'Accept: application/json' \

...


     --url 'https://api.ticketevolution.com/v9/orders/{order_id}/deliver_etickets' \
     -d '{"etickets":["item_id":12345,"eticket":"<base64-encoded file>"]}'

Physical Tickets

FedEx

If the shipment type for an order is FedEx there is a two step process to getting the airbill.

Local Pickup

For orders where the shipment type is LocalPickup both the buyer and seller need to provide they information so that they can arrange to meet for the local pickup.

...

Versions Compared

Old Version 11

New Version Current

Key

Processing Ticket Evolution Orders via API

Helpful tools

Create a User for Your Order Processor

Establish API Credentials for Your Order Processor

Use the API to Retrieve a List of Orders With a `state` of `pending` and a `type` of `Order`

A pseudo-code example of what you probably want to do

Differentiating Order Types

Getting Notified of New Orders

Order Integration

Webhooks

Polling

Differentiating Order Types

Sales to TEvo

Sales to a Client

Accepting an Order

Fulfilling Orders

Mobile Tickets

Etickets (Print at Home or QR codes)

Delivering Separate Files for Each Page

Delivering All Tickets in a Single File

Physical Tickets

FedEx

Local Pickup

Related articles

Page Comparison

Versions Compared

Old Version 11

New Version Current

Key

Processing Ticket Evolution Orders via API

Helpful tools

Create a User for Your Order Processor

Establish API Credentials for Your Order Processor

Use the API to Retrieve a List of Orders With a state of pending and a type of Order

A pseudo-code example of what you probably want to do

Differentiating Order Types

Getting Notified of New Orders

Order Integration

Webhooks

Polling

Differentiating Order Types

Sales to TEvo

Sales to a Client

Accepting an Order

Fulfilling Orders

Mobile Tickets

Etickets (Print at Home or QR codes)

Delivering Separate Files for Each Page

Delivering All Tickets in a Single File

Physical Tickets

FedEx

Local Pickup

Related articles

Use the API to Retrieve a List of Orders With a `state` of `pending` and a `type` of `Order`