| TABLE OF CONTENTS |
Getting Started
One of the first integrations ACME partners take on is a custom eCommerce solution. The ACME APIs make it easy to fully integrate the ticket purchase flow into your existing website using a few simple calls. This document provides a high-level overview of the calls needed to complete the checkout flow and is intended to be a supplement to other, more detailed, documentation.
Before getting started, we recommend you read the following guides:
Checkout Process Overview
The checkout process consists of 4 basic steps. While there are some variations based on the type of item being purchased, the sale channel used, or other configuration considerations, the high-level structure follows the path below. Click on the links to see the ACME-recommended endpoints to use in building your custom integration.
- Get a list of events available for purchase
- Create a shopping cart
- Checkout
- Get order details
Postman Collection
We created this Postman collection so our developer community could get some quick, hands-on experience using the ACME APIs for a simple checkout flow.
Prerequisites
- An active ACME Sandbox environment
- Valid user credentials with the ability to access ACME's Back Office
Using the Collection
There are 11 API calls in the collection that demonstrate the process of buying tickets to an event via the ACME APIs. Before you begin, you'll need to do the following:
- Import the collection into Postman
- Select the "Get Session" call
- Navigate to the "Pre-request Script" tab and update the environment, email address, and password
Note: The calls in the collection should be run in order, as many of them set environment variables that are used later in the flow.
| Step | Call | What's Happening | Prerequisite |
|---|---|---|---|
| 1 | Get Session | Creates an API session using your valid user credentials that will be used to authenticate many of the subsequent calls | |
| 2 | Get Event Instances | Retrieves a list of event instances scheduled for today, chooses the first item, and sets environment variables for instanceId and ticketTypeId | 1 |
| 3 | Create a Shopping Cart | Creates a new shopping cart with 2 tickets to the event info from Step 2 and set the cartId environment variable | 2 |
| 4 | Update a Shopping Cart | Updates the cart created in Step 3 | 3 |
| 5 | Retrieve a Shopping Cart | Retrieves the cart created in Step 3 | 3 |
| 6 | Checkout with Cart | Completes a checkout using the shopping cart created in Step 3 and sets the orderId environment variable | 3 |
| 7 | Checkout without Cart | Completes a checkout without using a pre-existing shopping cart and sets the orderId environment variable | 3 |
| 8 | Retrieve Order | Retrieves the order created in Step 6 or Step 7 | 6 or 7 |
Download the Postman collection attached at the end of this guide.
Note: This collection also includes additional ReAPIs that are used by OTA reservations and don't apply to online checkout.
ACME Recommended Workflow
1. Getting a list of available events, tickets, and prices
When building a checkout flow, the first thing you'll need to do is get a list of available event templates and instances. The event instance object contains all of the event and ticket information needed to successfully purchase tickets for a particular event. There are many endpoints to choose from, but we recommend using one of the endpoints below.
Recommended Endpoints:
GET /v2/b2c/event/templates/summaries |
Returns: A list of event template objects. This endpoint will give you all of the template-level information related to an event and is useful for displaying a full list of all templates available for sale. To complete a checkout, you'll need to pass a template ID into one of the calls below to get instance-level information about a specific event.
GET /v2/b2c/event/templates/instances |
Returns: This call returns a list of all event instances scheduled during a specified period of time. The startTime and endTime parameters are not required but are highly recommended. If you don’t send them, this call only returns event instances scheduled for today. This call will give you all the information you need to complete a checkout.
Note: To get instances for a single event template, pass the template ID into the call.
GET /v2/b2c/event/templates/times |
Returns: This call returns all Event Instances scheduled during a specified period of time grouped by Event Template. The startTime and endTime parameters are not required but are highly recommended. If you don’t send them, this call only returns event instances scheduled for today. This endpoint and the instances endpoint are similar, this one is just a little more organized.
Note: To get times for a single event template, pass the template ID into the call.
Event Template Documentation and Event Instances Documentation
2. Using a shopping cart (optional but highly recommended)
Shopping carts are a good way to manage the checkout flow if someone is purchasing multiple items in one session. After the initial cart is created, it can be updated with additional items. When you're ready to check out, you simply pass the shopping cart ID into the checkout object rather than adding all of the items at checkout.
Note: When doing an organization checkout, you will not use the shopping cart. You'll add the items to the checkout object.
3. Checking Out
There are two options to complete a basic checkout: simple checkout and CORS checkout. The difference between the two is that a CORS checkout can be completed from the front end of your site without exposing your API key. A simple checkout would need to go through your backend like most of the other calls in the checkout flow.
Note: Implementing a CORS checkout process requires additional configuration. See the documentation for more details.
4. Retrieving an Order
After a successful checkout, an order is created and the high-level order object is returned from the API. If your integration requires more detailed information about the order, including individual ticket UUIDs, you can pass the order ID into the will call endpoint.