Working with Agents via the Agency API

Rachael Norris
Rachael Norris
  • Updated

In this article, we’ll cover how to set up Events so that Agencies can sell tickets on your behalf using the Agency API. 

TIP: This article covers what your organisation needs to do in your Spektrix system in preparation for allowing Agents to sell using the Agency API. If the Agent needs assistance setting up the Agency API, there are guides on the Integrate Portal. Agents are also welcome to contact our Support Team.

Before starting, make sure you have read and followed the steps in:

In this article, we’ll take you through the following steps:


Setting up an Event for sale through the Agency API

Once you have created the Customer Record for your Agency, you are then able to select which Events and Instances Agents have access to through the Agency API.

This is done at the Instance level, in the Start Selling panel.

TIP: You can update multiple Instances by using the Bulk Instance Update Tool.

To do this go to the Admin Interface > Events and select the Event and then Instance you want to grant permission for Agents to sell.  

Check the boxes marked Visible and On Sale next to Agent. 

You can enter a date and time in the Start Selling column to start selling to Agents at a time in the future. If you leave this column blank the Instance will become available to Agents instantly.

An off sale time is required under the Sell until column. This is the time that the Instance will go off sale. It is set to the default Sell until time created in the Settings interface but can be changed.

Click Save to confirm your changes.


Managing Agency sales via the Agency API

Once an Instance is on sale and visible to Agents, Agents will be able to access the live seating plan for your Instance.

Using the Agency API you can allow Agents to sell as many tickets as they can without restriction or you can also use Locks to limit the number of tickets an Agent can sell. 

If you don’t wish to limit Agency sales, move on to the Agent Transactions heading.

If you do want to limit the number of tickets an Agent can sell, follow the steps in the next section to set up Agency Locks. 


Setting up Agency Locks

Agency Locks work by Locking a number of seats to only be accessed by Customer Records with a specific Agent Tag.

You can increase or decrease an allocation of Locked seats as needed and, using the API, this will be reflected to the Agent.

In this section there are three steps:

  1. Creating new Lock Types 
  2. Using Tags to limit the Customer Eligibility
  3. Applying a Lock Overlay

Before setting up Agency Locks, we recommend having an agreement in place with the Agent you are working with about the number of tickets you wish to sell.

An Agent will also need to set up their API integration so that they only sell from the Locked seats they have been allocated

TIP: If the Agent you are working with needs assistance setting up the Agency API there are guides on the Integrate Portal about selling from an allocation. They are also welcome to contact our Support Team.

You’ll need to follow this process for each of the Agents you want to work with.


Creating new Lock Types

To set up Locks for an Agency allocation, first go to the Admin Interface > Seating Plans > Locks. 

Create a new Lock Type for each of the Agents you plan to work with. You can find out more about Locks in the Introduction to Locks and Setting Up and Editing Lock Types.

To make a Lock Type available for Agents in the API you need to check the box marked Available for agents

WARNING: Leave the Require a password? box unchecked otherwise the Agent will not be able to sell the locked seats.


Limiting Access with Tags

You may also want to set Customer Eligibility using Tags or Attributes to limit the Locks to only those with the Agent Tag or specific Agents.  You can also create a Tag for each of the Agents you work with, limiting certain seats to specific Agents.


Applying a Lock Overlay

Next, you’ll need to apply a new Lock Overlay to each of the Events or Instances you plan to sell through Agents. You can choose to do this at the Global level (to all the Events using the Seating Plan), or, at the Instance level (to individual Instances).

Create a new Lock Overlay or edit an existing one for each of the Seating Plans you plan to use. 

TIP: You’ll need to add a Lock Overlay for both reserved and unreserved Seating Plans.

Apply the Agency Lock Type to each of the seats you will be selling to each Agency in a reserved seating plan or assign a number of seats to the Agency Lock Type in an unreserved seating plan. Take a look at How to Create and Edit Lock Overlays for step by step guidance.

With the Locks in place, the Agent will also need to set up their API integration so that they only sell from the Locked seats they have been allocated. Agents should refer to the Guide for Agents for more information.


Agent transactions

When an Agent processes a sale via the Agency API, the order appears in your system in the same way a web transaction might. 

Agency transactions can also be seen in the Open Transactions list in the same way as any other transaction. Once confirmed, the order will appear in the Sales Interface under Orders. Learn more in the Finding Agency API Orders article.

When an Agent processes an order via the API they can supply you with some extra details to help identify the order with your system. These fields are:

  • First Name
  • Last Name
  • First Line of Address
  • Agent Order Reference

These fields will appear automatically on Orders processed by Individual Customer Records with Agent Commission structures.


Waive Criteria

It is possible to exclude Agency Sales from fees such as Ticket Commission and Transaction Commissions

To do this, you will need to have an Attribute or Tag set up to identify Agent customer records. With this in place, go to the Admin Interface > Pricing > Ticket Commissions or Transaction Commissions

Select the Commission structure you wish to edit. 

When you are in the Basic Details tab, click Next to go to the Waive Criteria tab. 

Select the criteria by which you can identify and exclude Agents. For example, you might choose Tags: Agent.


Delivery Methods

When selling via the Agency API, Agents have two delivery options available to them:

  1. COBO/Will Call: The customer will collect the tickets from your venue. You as the organisation are responsible for the printing and fulfilment of the tickets. If an agency is selling on behalf of the venue, but the tickets are for collection, customer details can be added to ticket designs for ease of collection. Read our article on Finding Agency Orders (link) to find out more.
  2. Care Of Agent: The Agent is responsible for getting the tickets to the customer. It’s up to the Agent whether this is via E-Tickets, Post, SMS, etc. Once a sale is made, the Agent will have access to the Spektrix Order number as well as the unique barcode reference for the tickets. The barcode and order number are available to the Agent regardless of the delivery method chosen. This means that if the Agent is printing the tickets, the order can still be searched for within Spektrix and scanned just like any other ticket on the door.


Payments via the Agency API

When an Agent processes a sale, the payment registers as Agent Credit payment / refund type. This can be found in the Credit, deposit & vouchers tab in the payment section of the Cart/Basket.

You will not directly receive the payment when a transaction is made through the API. Instead, payments made through the API will go directly to the Agent. 

To collect the payment, you will need to invoice the Agent. How often you exchange funds will depend on your agreement with the Agent. 

Take a look at our article on Reporting for Agencies for more information on how to invoice Agents.


Returns and refunds

Agents only have access to sell tickets via the API. 

Depending on your agreement with an Agent, every approach to handling returns will be different. However, as a rule, if an Agent needs to process a refund to the customer this should be handled by the Agent outside of Spektrix. Once the Order has been returned, the Agent will then need to let you know to return the Order. 

In the Cart/Basket, you'll need to navigate to the Credit, deposit & vouchers tab and select Agent credit payment / refund to return the tickets for the Agent.



Further Reading

To continue learning about how to work with Agencies and Spektrix, take a look at the following articles: