NAV Navbar

guestmanagerAPI Documentation

JSON

Introduction

REST

Base URL

Api Version URL
Latest https://app.guestmanager.com/api/public
v1 https://app.guestmanager.com/api/public/v1

Versioning

The version is specified in the request URL. If the version is omitted, the latest version will be used by default.

Rate limiting

API requests are throttled by IP address and limited to 300 requests per 5 minute period.

Tooling

Postman is a great app for testing and experimenting with our API.

Feedback

Do you have a suggestion on how we can improve this API? Email us at support@guestmanager.com.

Requests

Headers

The following headers must be specified in all API requests.

Header Value
Authorization Token abcdefg
Content-Type application/json
Accept application/json

Parameters

All parameters should be submitted as JSON, however url-encoded data is also suitable. Provide only the attributes that you wish to change - do not submit the entire object, as you will likely encounter an error due to read-only attributes.

Responses

All responses are returned as JSON, along with a relevant status code.

You may change how results are returned by specifying an adapter in the GET request.

adapter Description
attributes Default. Array of objects, with no top-level key.
json* Array of objects, with a top-level key, and pagination information.
json_api** Conforms to the JSON API spec.

Successful status codes

Code Description
200 OK
201 Created
204 No Content -- used for DELETE requests.

Errors

Error status codes

Error Code Meaning
400 Bad Request
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- API Key is not authorized to perform this action.
404 Not Found -- The requested resource could not be found.
405 Method Not Allowed -- Request URL invalid.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The requested resource is no longer available.
422 Unprocessable Entity -- validation failed.
429 Too Many Requests -- You're making too many requests.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Exceptional errors

Exceptions vary in format. Please see the right hand panel for examples.

Attribute Type Meaning
type string forbidden, not_found, routing_error, parameter_missing, unpermitted_parameters
message string Description of the error.
detail object Detailed information on the error, depending on the error.

rate_limit_exceeded

{ "type": "rate_limit_exceeded", "message": "Throttle limit reached. Retry later." }

not_found

{
    "type": "not_found",
    "message": "Resource not found: Couldn't find Order with 'id'=1762272 [WHERE \"orders\".\"deleted_at\" IS NULL AND \"orders\".\"company_id\" = $1]",
    "detail": {
        "id": "1762272",
        "model": "Order",
        "primary_key": "id"
    }
}

parameter_missing

{
    "type": "parameter_missing",
    "message": "param is missing or the value is empty: order"
}

unpermitted_parameters

{
    "type": "unpermitted_parameters",
    "message": "found unpermitted parameter: :total",
    "detail": {
        "params": [
            "total"
        ]
    }
}

Validation errors

Validation errors occur when a provided attribute does not meet the validation requirements on the model. The status code is always 422.

Example Validation Error

{
    "type": "validation_error",
    "message": "Email is invalid",
    "errors": {
        "attributes": [
            {
                "field": "email",
                "label": "Email",
                "code": "invalid",
                "message": "is invalid"
            }
        ],
        "associations": {
            "tickets": {},
            "form_responses": {}
        }
    }
}

Example Validation Error w/ Associations

{
  "type": "validation_error",
  "message": "",
  "errors": {
      "attributes": [],
      "associations": {
          "tickets": {
              "2148094": {
                  "type": "validation_error",
                  "message": "Name can't be blank",
                  "errors": {
                      "attributes": [
                          {
                              "attribute": "name",
                              "label": "Name",
                              "code": "blank",
                              "message": "can't be blank"
                          }
                      ],
                      "associations": {}
                  }
              }
          },
          "form_responses": {}
      }
  }
}

Error response

Attribute Type Meaning
type string always validation_error
message string All of the validation errors concatenated into a single message.
errors object Details on the individual validation errors. Look for the key relevant to the resource you are modifying. E.g. for Orders, the key is order
errors[attributes] array Errors on the object itself.
errors[associations] hash Errors on associated objects.

Error node

Attribute Type Meaning
attribute string The attribute on the model that triggered the error.
label string A human readable version of the attribute.
code string The type of validation error. See below for possibile codes.
message string A human readable version of the code

Association errors

When you are submitting nested parameters, e.g. tickets with an Order, the errors associated to those resources are specified in an array, in the errors attribute, with the key being the name of the association. E.g. for tickets submitted along with an order, the key to access those is errors.associations.tickets Inside the association errors key, you will find a hash, indexed by the ID of the associated record. See example.

Validation error codes

https://github.com/rails/rails/blob/master/activemodel/lib/active_model/locale/en.yml

code Meaning
blank attribute is required
invalid attribute format is invalid.

Topics

Authentication

Authentication is done through the Authorization request header. The value should be in the format Token abcdefg where abcdefg is replaced with your API Key.

Request

curl -X GET \
  https://app.guestmanager.com/api/public/v1 \
  -H 'Authorization: Token abcedf123' \
  -H 'Content-Type: application/json'

Response

{
  "id": 0,
  "name": "Your company name"
}

API keys

API Keys are created in the company dashboard under the Config menu. API keys are authorized for either read, write, or both.

API key permissions

API Keys are authorized for read, write, or both.

Attribute Allowed request methods
read GET
write POST, PATCH, DELETE

Common attributes

All resources have the following attributes.

Attribute Type Description
id integer Unique identifier for the resource. read-only
created_at datetime When the record was created. read-only
updated_at datetime When the record was last updated. read-only
deleted_at datetime When the record was deleted. read-only

Data types

Type Example Description
datetime "2017-10-25T17:54:51.557604Z" iso8601 format in the UTC time zone.
decimal 102.56 All monetary amounts are returned as a string to two decimal places.

Filters

Parameter Format Example
ids Comma separated string or JSON array. "1,2,3" or json {"ids": [1,2,3]}

Pagination

For resource collection endpoints, the following parameters can be used to paginate responses.

Parameter Default Description
per_page 10 How many records to return in each response.
page 1 The page to return records for.

Fields and relationships

To increase performance and optimize network traffic, you may specify only the fields and relationships you interested in. Refer to a specific resource endpoint to see which fields and relationships are available.

Parameter Options
fields Comma separated string of the attributes you are interested in for that particular model.
includes Comma separated string of the relationships you are interested in for that particular model.

Sorting

For resource collection endpoints, you can sort by the following common attributes, or any resource-specific attribute (e.g. start_date for Event)

Parameter Options
sort_dir asc or desc
sort_by id, created_at, updated_at, or any resource specific attribute.

Events

Event properties

Attribute Type Description
name string Name of the series.
slug string
venue_id integer
parent_event_id integer The series this event belongs to.
published_at datetime When the event was published.
position integer Sorting.
calendar_id integer Calendar this event belongs to.
categories array Categories associated to this event.
links object manage, event_page, order_page
start object tz, local, utc
end object
running boolean
past boolean
future boolean
selling boolean
graphics object banner, background
venue object
tags array
ticket_tiers array

Start and end attributes

For convenience, start and end are provided as objects, each containing tz, local, and a utc attribute.

{
  "tz": "Melbourne",
  "local": "2016-10-31T11:00:00+11:00",
  "utc": "2016-10-31T00:00:00Z"
}
Attribute Type Description
tz string Venue time zone.
local string datetime in the venue time zone.
utc string datetime in UTC (global) format.

List events

GET
/events

Request parameters

Attribute Type Default Values
fields string none links
sort_by string none start_date, end_date, name, parent_event_id, venue_id, published_at, position
include string none tags, categories, ticket_tiers, ticket_tiers.price_levels, venue, venue.address
venue_id integer none Filter by a specific venue.
parent_event_id integer none Filter by event series.
category_id integer none Filter by category.
status string none active: events in progress and future events
over: events where end_date < current time
future: events with start dates in the future (excludes active events)
past: events where start_date is less than current time
this_week: Monday-Sunday
next_week: Next Monday-Sunday
published boolean none true or false
name string none Runs a case insensitive query to match any events containing this query. Only use for user-generated searching as this is slower, and querying attributes directly (like parent_event_id and venue_id) is going to be much more reliable.
start_date[range_start] date or datetime none Beginning start date range.
start_date[range_end] date or datetime none Ending start date range.
end_date[range_start] date or datetime none Beginning end date range.
end_date[range_end] date or datetime none Ending end date range.

Fetch event

GET
/events/{id}

Create event

POST
/events

Request parameters

Attribute Type Required Description
event[name] string yes Name of the event.
event[venue_id] integer yes id of the venue. Please find or create a venue first.
event[start_date] datetime yes Start date and time of the event.
event[end_date] datetime yes End date and time of the event.

Fetch ticket tiers

Returns the bookable items for an event.

Each Tier has at least one Price Level. The variant_id in the price_levels array is important, because it’s used to create an Order.

GET
/events/{id}/ticket_tiers

Request parameters

Attribute Type Default Values
{id} integer required Event ID.
include string price_levels price_levels

Ticket types

Ticket types are composed of two data models: ticket type, and event ticket type. A ticket type is a standalone entity that can be re-used for many different events. An event ticket type associates a ticket type to a specific event.

Ticket type properties

Attribute Type Default Description
name string Name of the ticket type.
display_name string What is displayed to the guest, e.g. on the PDF. Defaults to the name if left blank.
pdf_template_id integer ID number of the associated PDF template.
wallet_template_id integer ID number of the associated Apple Wallet template.
transferable boolean true Whether guests can transfer this ticket type to another guest.
attachable boolean true Whether tickets are attached in emails (true) or provided as a download link (false).

Event ticket type properties

Attribute Type Description
ticket_type_id integer ID of associated ticket type.
event_id integer ID of associated event.
starts_at datetime When this ticket is valid from. Display purposes only.
ends_at datetime When this ticket is valid until. Display purposes only.
pdf_template_id integer Override the ticket type if necessary.
wallet_template_id integer Override the ticket type if necessary.

Create a ticket type for an event

Request

POST
/event_ticket_types

Parameters

Parameter Type Description
event_ticket_type Event ticket type See properties above.
event_ticket_type[ticket_type_attributes] Ticket type See properties above. Used to create a new ticket type. Required if event_ticket_type[ticket_type_id] is not provided.

Examples

See example requests on the right.

Create a ticket type and add it to an event

{
  "event_ticket_type": {
    "event_id": 12345,
    "ticket_type_attributes": {
      "name": "GA"
    }
  }
}

Add an existing ticket type to an event

{
  "event_ticket_type": {
    "event_id": 12345,
    "ticket_type_id": 10001
  }
}

Ticket Tiers

Tier properties

Attribute Type Description
event_id integer Event this tier belongs to.
parent_tier_id integer Parent TicketTier
product_id integer Product this tier belongs to.
ticket_type object TicketType this tier belongs to.
price_levels array Array of TicketTierLevel

Tier level properties

Attribute Type Description
name string Name.
ticket_tier_id integer TicketTier
variant_id integer ID of the related product - used to create LineItem's
price decimal The variant's price.
currency string The variant's currency.
status string Current selling status of the variant.
count_on_hand integer How many are in-stock.
variant object The related variant.

Recurring events

Top level non-bookable events that serve as the wrapper around individual event date/times. The ID of the class can be used to query against the Events API to return date/times for that series.

Properties

Attribute Type Description
name string Name of the series.
position integer Sorting.
calendar_id integer Calendar this series belongs to.
categories array Categories associated to this series.
tags array Tags associated to this series.

List recurring events

GET
/series

Request

Attribute Type Default Values
include string none tags, categories
published_at string none published, unpublished

Event Categories

An event can have many categories.

Category properties

Attribute Type Description
name string Name of the category.
description text Description.
subtitle string Subtitle.
position integer Sorting.
short_description text Shorter description.
icon_url string URL for the icon image.
children array Sub-categories.

List categories

GET
/categories

Request parameters

Attribute Type Values
sort_by string name, position

Venues

Venue properties

Attribute Type Description
name string Name of the venue.
description text Additional line can be used to describe the venue.
slug string Auto-generated for use in url-generation.
time_zone string Time zone where the venue is located.
latitude string Latitude of venue. Used for Apple Wallet.
longitude string Longitude of venue. Used for Apple Wallet.
address_id integer ID of the associated address.
address object Address of the venue. See Address.

List venues

GET
/venues

Create venue

POST
/venues

Create a basic venue

{
  "venue": {
    "name": "My venue",
    "time_zone": "Pacific Time (US & Canada)"
  }
}

Time zones

Use the first column in the table below to determine which time zone to submit.

Name TZ UTC Offset
International Date Line West Etc/GMT+12 -12:00
American Samoa Pacific/Pago_Pago -11:00
Midway Island Pacific/Midway -11:00
Hawaii Pacific/Honolulu -10:00
Alaska America/Juneau -09:00
Pacific Time (US & Canada) America/Los_Angeles -08:00
Tijuana America/Tijuana -08:00
Arizona America/Phoenix -07:00
Chihuahua America/Chihuahua -07:00
Mazatlan America/Mazatlan -07:00
Mountain Time (US & Canada) America/Denver -07:00
Central America America/Guatemala -06:00
Central Time (US & Canada) America/Chicago -06:00
Guadalajara America/Mexico_City -06:00
Mexico City America/Mexico_City -06:00
Monterrey America/Monterrey -06:00
Saskatchewan America/Regina -06:00
Bogota America/Bogota -05:00
Eastern Time (US & Canada) America/New_York -05:00
Indiana (East) America/Indiana/Indianapolis -05:00
Lima America/Lima -05:00
Quito America/Lima -05:00
Atlantic Time (Canada) America/Halifax -04:00
Caracas America/Caracas -04:00
Georgetown America/Guyana -04:00
La Paz America/La_Paz -04:00
Puerto Rico America/Puerto_Rico -04:00
Santiago America/Santiago -04:00
Newfoundland America/St_Johns -03:30
Brasilia America/Sao_Paulo -03:00
Buenos Aires America/Argentina/Buenos_Aires -03:00
Greenland America/Godthab -03:00
Montevideo America/Montevideo -03:00
Mid-Atlantic Atlantic/South_Georgia -02:00
Azores Atlantic/Azores -01:00
Cape Verde Is. Atlantic/Cape_Verde -01:00
Casablanca Africa/Casablanca +00:00
Dublin Europe/Dublin +00:00
Edinburgh Europe/London +00:00
Lisbon Europe/Lisbon +00:00
London Europe/London +00:00
Monrovia Africa/Monrovia +00:00
UTC Etc/UTC +00:00
Amsterdam Europe/Amsterdam +01:00
Belgrade Europe/Belgrade +01:00
Berlin Europe/Berlin +01:00
Bern Europe/Zurich +01:00
Bratislava Europe/Bratislava +01:00
Brussels Europe/Brussels +01:00
Budapest Europe/Budapest +01:00
Copenhagen Europe/Copenhagen +01:00
Ljubljana Europe/Ljubljana +01:00
Madrid Europe/Madrid +01:00
Paris Europe/Paris +01:00
Prague Europe/Prague +01:00
Rome Europe/Rome +01:00
Sarajevo Europe/Sarajevo +01:00
Skopje Europe/Skopje +01:00
Stockholm Europe/Stockholm +01:00
Vienna Europe/Vienna +01:00
Warsaw Europe/Warsaw +01:00
West Central Africa Africa/Algiers +01:00
Zagreb Europe/Zagreb +01:00
Zurich Europe/Zurich +01:00
Athens Europe/Athens +02:00
Bucharest Europe/Bucharest +02:00
Cairo Africa/Cairo +02:00
Harare Africa/Harare +02:00
Helsinki Europe/Helsinki +02:00
Jerusalem Asia/Jerusalem +02:00
Kaliningrad Europe/Kaliningrad +02:00
Kyiv Europe/Kiev +02:00
Pretoria Africa/Johannesburg +02:00
Riga Europe/Riga +02:00
Sofia Europe/Sofia +02:00
Tallinn Europe/Tallinn +02:00
Vilnius Europe/Vilnius +02:00
Baghdad Asia/Baghdad +03:00
Istanbul Europe/Istanbul +03:00
Kuwait Asia/Kuwait +03:00
Minsk Europe/Minsk +03:00
Moscow Europe/Moscow +03:00
Nairobi Africa/Nairobi +03:00
Riyadh Asia/Riyadh +03:00
St. Petersburg Europe/Moscow +03:00
Volgograd Europe/Volgograd +03:00
Tehran Asia/Tehran +03:30
Abu Dhabi Asia/Muscat +04:00
Baku Asia/Baku +04:00
Muscat Asia/Muscat +04:00
Samara Europe/Samara +04:00
Tbilisi Asia/Tbilisi +04:00
Yerevan Asia/Yerevan +04:00
Kabul Asia/Kabul +04:30
Ekaterinburg Asia/Yekaterinburg +05:00
Islamabad Asia/Karachi +05:00
Karachi Asia/Karachi +05:00
Tashkent Asia/Tashkent +05:00
Chennai Asia/Kolkata +05:30
Kolkata Asia/Kolkata +05:30
Mumbai Asia/Kolkata +05:30
New Delhi Asia/Kolkata +05:30
Sri Jayawardenepura Asia/Colombo +05:30
Kathmandu Asia/Kathmandu +05:45
Almaty Asia/Almaty +06:00
Astana Asia/Dhaka +06:00
Dhaka Asia/Dhaka +06:00
Urumqi Asia/Urumqi +06:00
Rangoon Asia/Rangoon +06:30
Bangkok Asia/Bangkok +07:00
Hanoi Asia/Bangkok +07:00
Jakarta Asia/Jakarta +07:00
Krasnoyarsk Asia/Krasnoyarsk +07:00
Novosibirsk Asia/Novosibirsk +07:00
Beijing Asia/Shanghai +08:00
Chongqing Asia/Chongqing +08:00
Hong Kong Asia/Hong_Kong +08:00
Irkutsk Asia/Irkutsk +08:00
Kuala Lumpur Asia/Kuala_Lumpur +08:00
Perth Australia/Perth +08:00
Singapore Asia/Singapore +08:00
Taipei Asia/Taipei +08:00
Ulaanbaatar Asia/Ulaanbaatar +08:00
Osaka Asia/Tokyo +09:00
Sapporo Asia/Tokyo +09:00
Seoul Asia/Seoul +09:00
Tokyo Asia/Tokyo +09:00
Yakutsk Asia/Yakutsk +09:00
Adelaide Australia/Adelaide +09:30
Darwin Australia/Darwin +09:30
Brisbane Australia/Brisbane +10:00
Canberra Australia/Melbourne +10:00
Guam Pacific/Guam +10:00
Hobart Australia/Hobart +10:00
Melbourne Australia/Melbourne +10:00
Port Moresby Pacific/Port_Moresby +10:00
Sydney Australia/Sydney +10:00
Vladivostok Asia/Vladivostok +10:00
Magadan Asia/Magadan +11:00
New Caledonia Pacific/Noumea +11:00
Solomon Is. Pacific/Guadalcanal +11:00
Srednekolymsk Asia/Srednekolymsk +11:00
Auckland Pacific/Auckland +12:00
Fiji Pacific/Fiji +12:00
Kamchatka Asia/Kamchatka +12:00
Marshall Is. Pacific/Majuro +12:00
Wellington Pacific/Auckland +12:00
Chatham Is. Pacific/Chatham +12:45
Nuku'alofa Pacific/Tongatapu +13:00
Samoa Pacific/Apia +13:00
Tokelau Is. Pacific/Fakaofo +13:00

Orders

Order properties

Example Response

{
    "id": 176260,
    "number": "GM720XKYDP5SLR",
    "state": "cart",
    "checkout_steps": [
        "email",
        "register",
        "tickets",
        "address",
        "form",
        "complete"
    ],
    "guest_id": null,
    "guest_checkout": false,
    "first_name": "Jeff",
    "last_name": "Blake",
    "email": "jeff.blake2@gmail.com",
    "phone_number": "+61491570156",
    "phone_number_country": "AU",
    "item_count": 1,
    "total": "0.0",
    "item_total": "0.0",
    "adjustment_total": "0.0",
    "promo_total": "0.0",
    "currency": "AUD",
    "completed_at": null,
    "expires_at": "2017-10-25T17:54:51.557604Z",
    "links": {
        "cart": "http://miele.guestmanager.dev:3000/cart?guest_token=5b8fa186f25a225fbe95744baf6326fb&id=GM720XKYDP5SLR",
        "checkout": "http://miele.guestmanager.dev:3000/cart/checkout/GM720XKYDP5SLR?guest_token=5b8fa186f25a225fbe95744baf6326fb"
    },
    "payment_methods": [
        {
            "id": 78,
            "type": "Gateway::Stripe",
            "name": "Stripe",
            "description": null,
            "display_name": "Credit Card",
            "currencies": [
                "AUD"
            ],
            "billing_address_required": true,
            "payment_profiles_enabled": true,
            "test_mode": false,
            "active": true,
            "tokenize_key": "pk_live_*****"
        }
    ],
    "line_items": [
        {
            "id": 176643,
            "order_id": 176260,
            "name": "Free",
            "description": null,
            "variant_id": 6522,
            "quantity": 1,
            "price": "0.0",
            "amount": "0.0",
            "currency": "AUD",
            "bundle_item_id": null,
            "ticket_tier": {
                "name": "Complimentary Owner Product Demonstrations",
                "event": {
                    "name": "Oven",
                    "date": "04-11-2017",
                    "time": "10:30am-12:00pm",
                    "venue": "Knoxfield"
                }
            }
        }
    ],
    "adjustments": [],
    "promotions": [],
    "tickets": []
}

Attribute Type Description
number string Order number. read-only
state string The current step of the order. See order states. read-only
checkout_steps array List of all states dynamically computed for this order. Can change from state to state. read-only
guest_id integer The guest associated to this order. read-only
guest_token string Unique token for the session. Submit this back to GM for any requests that modify this order. read-only
payment_state string Current payment status. See payment states. read-only
currency string ISO code of currency. All items added to order must have a price available in this currency.
item_count integer Number of items in the order. Sum of all line_item.quantity read-only
total decimal Grand (net) total, after adjustments, promotions, fees, and taxes. read-only
item_total decimal Sum of all line_item.price x line_item.quantity read-only
adjustment_total decimal Sum of all non-line-item charges (promotions, taxes, fees, etc). read-only
payment_total decimal Sum of all completed payments. read-only
additional_tax_total decimal Additional taxes passed onto the guest. read-only
included_tax_total decimal Included taxes. read-only
included_service_fee_total decimal Included fees. read-only
additional_service_fee_total decimal Extra fees passed onto the guest. read-only
promo_total decimal The discount on this order. read-only
shipment_total decimal Total shipping charges. read-only
taxable_adjustment_total decimal
non_taxable_adjustment_total decimal
application_fee_total decimal The fee charged by Guest Manager. read-only
merchant_fee_total decimal The portion of service fees collected that are denoted as merchant fees. read-only
expires_at datetime When the items are released back into inventory. Default 15 minutes.
completed_at datetime When the order was completed. read-only
abandon_at datetime When the order will be marked as abandoned. Configured via CheckoutCustomization read-only
can_checkout_at datetime If the order is reserved, the time at which the order will be eligible for completion. read-only
created_by_id integer The admin who created this order. read-only
canceler_id integer The admin who canceled this order. read-only
approver_id integer The admin who approved this order. read-only
holder_id integer The admin who held this order. read-only
company_id integer The company associated to this order. read-only
checkout_customization_id integer The checkout configuration. read-only
zone_id integer Tax zone. read-only
order_form_id integer Related order form.
order_channel_id integer Related order channel for tracking purposes.
shipping_method_id integer Chosen shipping method.
bill_address_id integer Billing address.
ship_address_id integer Shipping address.
shipment_state string Status of shipment.
email_state string
metadata hash Extra data stored in order.
mobile boolean If the order was placed on a mobile device.
locked boolean If the order is locked for updates.
last_ip_address string Last known ip address of guest.
message text Admin note.
Attribute Type Description
bill_address object Billing address.
ship_address object Shipping address.
line_items array Items in the order.
payment_methods array Available payment methods.
tickets array Tickets relevant to the line items.
responses array Surveys/questions.
payments array Payments made on this order.
promotions array If any promo's were applied to this order. If so, a corresponding Adjustment will be present on the order or line item.

Guest checkout properties

Add these attributes through either the create or update order endpoint. The guest_id attribute will be set on the order through a find or create process based on the provided email and phone number.

Attribute Type Description
guest_checkout boolean Set this to true to enable guest checkout.
first_name string First name of guest.
last_name string Last name of guest.
email string Email address of guest. Format is validated.
phone_number string Phone number of guest.
Format is validated according to the phone_number_country provided.
phone_number_country string Country of the phone number. 2 digit ISO code, uppercase.

Line item properties

Attribute Type Description
order_id boolean Set this to true to enable guest checkout. read-only
name string Variant name. read-only
description string
variant_id integer The product variation in the cart.
quantity integer number of items.
price decimal per unit price.
amount decimal price * quantity read-only
currency string ISO code.
bundle_item_id integer The parent LineItem this LineItem is bundled under. read-only
ticket_tier object Present if a ticket tier is being sold. read-only
adjustments array adjustments related to this line item. (fees, taxes, promotions) read-only
tickets array Tickets issued as specified by the variant's package. read-only

Ticket tier properties

Attribute Type Description
name string The Ticket Type name.
event object
event.name string Name of the event.
event.date date Localized date of the event.
event.time time Localized time of the event.
venue string Name of the venue where event is held.

Line item validation errors

code Meaning
not_available Product is no longer on sale. Could be disabled, or past the end_sale_at date.
sold_out Product is sold out.

Adjustment properties

Attribute Type Description
label string Description of the adjustment.
order_id integer Order. read-only
adjustable_id integer ID of what this adjustment is adjusting read-only
adjustable_type string The model of what this adjustment is adjusting. One of Order or LineItem read-only
amount decimal Dollar amount.
source_id integer ID of what created this adjustment. read-only
source_type string The model of what created this adjustment. One of ServiceFeeRate, TaxRate, PromotionAction read-only
included boolean Whether the amount is included in the adjustable total, or added on top. read-only
mandatory boolean
eligible boolean If this adjustment is eligible, determined by source read-only
groupable boolean Whether this adjustment can be grouped into a total amount (e.g. taxes), or must be listed out separately. read-only
finalized boolean If this adjustment can be modified. read-only
merchant_fee boolean If this adjustment is used to cover credit card processing fees. Determined by the ServiceFeeRate read-only
application_fee boolean If this amount is monies owed to Guest Manager. read-only

Payment properties

Attribute Type Description
number string Unique identifier.
amount decimal Payment amount.
state string status of the payment.
order_id integer Order ID.
source_id integer
source_type string
payment_method_id integer
response_code string Response from payment gateway. Typically is the unique identifier used by the gateway.
application_fee decimal Monies routed to Guest Manager.
reason string A decline reason.

Order states

state Description
cart Default state for all newly created orders.
expired Order was not completed within 15 minutes of creation. Can be resumed.
voided Voided by an admin. Cannot be resumed.
canceled Canceled by admin or guest. Cannot be resumed.
abandoned No action was taken on order X hours after expired. Enabled if Abandoned Cart Recovery feature is configured.

Payment states

payment_state Description
paid payment_total == total
balance_due payment_total < total
credit_owed payment_total > total
partial_refund Some items have been refunded.
refunded All items have been refunded.
failed Payment failed.

Exceptional errors

Exceptions vary in format. Please see the right hand panel for examples.

type Meaning
cannot_modify Order is in an uneditable state. (e.g. complete)

Create an order

Request

POST
/orders

Parameters

Parameter Description
order[currency] Optional if your account is not enabled for multi-currency.
order[line_items]
transition_order Include this parameter to automatically being the checkout process.

Empty order

{
  "order": {
    "currency": "USD"
  }
}

Order w/ line items

{
  "order": {
    "currency": "USD",
    "guest_checkout": true,
    "first_name": "Jeff",
    "last_name": "Blake",
    "email": "jeff@guestmanager.com",
    "phone_number": "2069405178",
    "phone_number_country": "US",
    "line_items": [
      {
        "variant_id": 12345,
        "quantity": 2
      }
    ]
  }
}

Fetch order

GET
/orders/{id}

Update order

Updates an order. All line items must be provided.

PATCH
/orders/{id}

Example Request

{
  "order": {
    "line_items": [
      {
        /* no ID present, creates new line item */
        "variant_id": 12345,
        "quantity": 4
      },
      {
        /* updates existing line item */
        "id": 12345,
        "variant_id": 9999,
        "quantity": 2
      }
    ]
  }
}

Request parameters

Parameter Description
{id} Order ID.
guest_token Provide the order's guest_token to authorize updates to this order.
transition_order Include this parameter to automatically being the checkout process.

Apply coupon code

Attempts to apply a coupon/promo code to the order.

PATCH
/orders/{id}/apply_coupon_code

Request parameters

Parameter Type Description
coupon_code string Optional if your account is not enabled for multi-currency.
guest_token string Provide the order's guest_token to authorize updates to this order.

Response

Status Description
200 Coupon successfully applied. Inspect the new total, promo_total, and adjustment_total
422 Error. Coupon not found, expired, inactive, or ineligible. Review the error message.

List orders

GET
/orders

Add items

“Add to cart” Adds specified quantity of the variant to the order.

POST
/orders/{order-id}/line_items/add

Request parameters

Parameter Type Description
variant_id integer The variant to add to the order.
quantity integer Quantity of variant_id to add.

Remove items

“Remove from cart” Removes specified quantity of the variant from the order.

POST
/orders/{order-id}/line_items/remove

Request parameters

Parameter Type Description
variant_id integer The variant to remove from the order.
quantity integer Quantity of variant_id to remove.

Delete line item

Deletes an entire line item from the order.

DELETE
/orders/{order-id}/line_items/{id}

Parameters

Parameter Type Description
{order-id} integer Order ID.
{id} integer The line item ID to delete. not the variant ID.

Update line item

PATCH
/orders/{order-id}/line_items/{id}

Request parameters

Parameter Type Description
{order-id} integer Order ID.
{id} integer The line item ID to delete. not the variant ID.
line_item[quantity] integer The quantity.

Checkout

There are two ways to implement the checkout process via the API.

The links attribute on the Order will specify a URL that you can redirect users to or open in an iFrame popup within your site. This will utilize the Guest Manager UI.

Order

{
  "links": {
    "cart": "...",
    "checkout": "..."
  }
}

API based checkout

For complete control of the checkout experience, you may implement the checkout step UI yourself and make API calls to transition the order forward.

Checkout states

state Enabled If Description
email Standard checkout mode.
register Standard checkout mode.
order_form Items in cart do not satisfy order form conditions.
customize A master variant was added to the cart, a specific variant needs to be chosen.
addon Any products in the order have addon relationships.
tickets Any ticket types in the order are set to collect name and/or email.
password Any event in the order is password protected.
invite An event in the order requires an invitation to proceed.
member Any ticket type in the order is set to collect a Member ID.
membership Any item in the order requires a membership to purchase.
address Billing or shipping address are required.
delivery Any item in the order requires shipping.
form Any event in the order has a form configured.
reserved Any item in the order is not currently onsale, but can be reserved.
requested Any item in the order is soldot, but can be requested (wait list).
conflict Any event in the order conflicts with another event in the order (if configured).
payment Order total is greater than 0.
confirm Setting to review order before placing is enabled.
processing Payment is currently processing in the background.
complete All previous states have been satisfied.

Standard checkout

Requires the guest to login or register. This method is not currently supported via the API.

Guest checkout

Allows the guest to checkout an order without authenticating or registering their email or phone number. The enable_guest_checkout option must be enabled on the CheckoutCustomization object. The order will require email, first_name, and last_name to be updated before transitioning the order from the cart step to the checkout process. phone_number and phone_number_country may also be provided.

Resuming an order

Inspect the expires_at attribute on the order. This is 15 minutes in the future by default. When this timer expires, the order is moved from whatever state it is currently, to expired. The tickets are released back to inventory When an order expires, need to resume it. Need to check that inventory was successfully re-reserved (e.g. if sold out, not on sale, tickets are not available).

PATCH
/checkout/{id}/resume

Request parameters

Parameter Description
{id} Order ID.
guest_token Provide the order's guest_token to authorize updates to this order.

Begin checkout

Attempt to move the order to the next step in the checkout process without providing any new attributes. Typically this is used for moving an order from cart to the first step in the checkout process, as this transition does not require any new attributes.

PATCH
/checkout/{id}/next

Request parameters

Parameter Description
{id} Order ID.
guest_token Provide the order's guest_token to authorize updates to this order.
state Optional. Attempt to move the order directly to this state.

Response

Upon successful transition to checkout, Inspect the state (string) and checkout_steps (array of strings) attributes on the Order and update your UI accordingly. The last step will be one of complete, requested, or reserved, depending on the availability and on-sale restrictions of the items in the cart.

Update and transition order

This is the sole endpoint for transitioning an order through the various checkout steps. Which step the order is on will dictate which attributes need to be submitted.

PATCH
/checkout/{id}

Request parameters

The following parameters should be submitted for every checkout step, along with the step-specific data.

Parameter Description
{id} Order ID.
guest_token Provide the order's guest_token to authorize updates to this order.
order[state] Provide the current state attribute that you are sending parameters for.
Step specific data. Include the relevent information specified below, according to the current step.

Response Errors

Every time this endpoint is called, the order is first checked for checkout eligibility, so it is important to handle all of these errors in every checkout step.

Refer to the section on errors for the JSON format of the response.

Error type Meaning
checkout_not_allowed
order_processing
order_complete
invalid_state Order cannot transition to provided state.

cart step

The default state of all newly created orders.

tickets step

The tickets step is included if the ticket type related to the line item in the cart has been set to include the name or email fields during checkout. The purpose of this step is to collect attendee information prior to completion of an order.

The tickets attribute on the order will dictate which tickets need to be updated with names and/or emails.

When the keep attribute is true, a name is not required, because that ticket is being assigned to the order.guest.

Example Request

{
  "order": {
    "state": "tickets",
    "tickets": [
      {
        "id": 123456,
        "keep": true
      },
      {
        "id": 987655,
        "name": "Bizzy Bone"
      }
    ]
  }
}

Example Response (Error)

{
    "type": "validation_error",
    "message": "",
    "errors": {
        "attributes": [],
        "associations": {
            "tickets": {
                "2148093": {
                    "type": "validation_error",
                    "message": "Name can't be blank",
                    "errors": {
                        "attributes": [
                            {
                                "field": "name",
                                "label": "Name",
                                "code": "blank",
                                "message": "can't be blank"
                            }
                        ],
                        "associations": {}
                    }
                }
            },
            "form_responses": {}
        }
    }
}

Request parameters

Parameter Description
order[tickets] Array. Include id, name, email, keep, for each ticket.

Notes

address step

This step is included if shipping is enabled for any of the line items, order total is greater than 0, and/or if the billing address is set to required for all orders (via the CheckoutCustomization), even if the order total is 0.

Example Request

{
  "order": {
    "state": "address",
    "bill_address": {
      "address1": "123 Main Street",
      "city": "Anytown",
      "zipcode": "92109",
      "state_id": 162,
      "country_id": 14
    },
    "ship_address": {
      "address1": "123 Main Street",
      "city": "Anytown",
      "zipcode": "92109",
      "state_code": "WA",
      "country_code": "AU"
    }
  }
}

State and Country information can either be provided from their respective id (fetched from the API), or as their ISO codes: state_code and country_code

Parameter Type Description
order[bill_address] object See Address for format.
order[ship_address] object See Address for format.

Response

Upon successful addition of address information, you will see a populated bill_address_id and/or ship_address_id.

form step

This step is included if a Form (i.e. Questions or Survey) has been configured on this order. Inspect the responses attribute on the Order.

Only the answers id and value need to be submitted back. For multiple choice fields, the answer.value will be the id of the FormFieldOption

Example Request

{
    "order": {
        "state": "form",
        "responses": [
            {
                "id": 38133, /* Response ID */
                "answers": [
                {
                    "id": 167288,
                    "value": "791" /* multiple choice */
                },
                {
                    "id": 167286,
                    "value": "592" /* multiple choice */
                },
                {
                    "id": 167287,
                    "value": "test"
                }
            ]
            }

        ]
    }
}

Example Response (Error)


Parameter Type Description
order[responses] array See FormResponse for format.

payment step

This step is included if the order total is greater than 0. Inspect the payment_methods attribute to see which options are available for payment.

Do not submit credit card information via the API. Use your payment provider's Javascript SDK to create a token instead.

Parameter Type Description
order[payments] array See Payment for format.

Example Request

{
    "order": {
        "state": "payment",
        "payments": [{
                "payment_method_id": 75,
                "source": {
                    "brand": "visa",
                    "last_four": "4680",
                    "token": "tok_1231231231312322",
                    "cvv": "123"
                }
            }

        ]
    }
}

Payment request parameters

Parameter Type Description
amount decimal Leave this blank and it will be automatically be set to the amount due on the order.
payment_method_id integer The payment method ID.
source.last_four string Last 4 digits on the credit card.
source.brand string Credit card type. One of visa, master, american_express, jcb, diners_club, or discover
source.token string The tokenized identifier of the credit card, created using the payment method SDK.
source.cardholder_name string Name of the card owner.
source.cvv string 3 or 4 digit code on the card to perform verification.

processing step

This step is not present in the checkout_steps attribute. Once payment information is submitted in the payment step, the payments are processed asynchronously during the processing state.

Poll the order until the state changes from processing. If payment failed, the state will return to payment. If successful, the order will be complete and in the complete state.

Poll order state

If the order is still processing, a single state attribute will be returned, for efficiency. If the order is no longer processing, you will receive a full Order object back.

GET
/orders/{id}/poll?guest_token=xyz

Example Response (Payment Processing)

{
  "state": "processing"
}

Example Response (Order Complete)

{
  "id": 1232323
  "state": "complete",
  "payment_state": "paid"
  /* attributes redacted */
}

complete step

Order is now complete. Tickets have been fulfilled. The order is not necessarily fully paid at this point. completed_at will be non-null.

Attribute Value
state complete
completed_at iso8601 datetime
payment_state `paid

requested step

Included if any of the products in the order are currently sold out, and the product has can_request attribute enabled.

reserved step

Included if any of the products in the order are not currently on sale, and the product has can_reserve attribute enabled.

Tickets

Ticket properties

{TBI}

Fetch a ticket

Request

GET
/tickets/{id}

Parameters

No parameters.

Create a ticket

Request

POST
/tickets

Parameters

Parameter Type Optional Description
ticket[name] string Yes Name to be shown on the ticket. Automatically set if guest_id is provided.
ticket[email] string Yes Email address of the ticket owner. Automatically set if guest_id is provided.
ticket[guest_id] int Yes Link a guest in your database as the owner of this ticket.
ticket[event_ticket_type_id] int Yes, if both event_id and ticket_type_id are provided. The Ticket Type to assign to the ticket.
ticket[dispatch] boolean Yes If true, an email is dispatched to the owner of the ticket, with the ticket as a PDF attachment.
ticket[barcode_id] string Yes A barcode number will be automatically generated if one is not provided.
ticket[list_id] int Yes The list to assign this ticket to. If not provided, defaults to the company master list.
ticket[permanent_list_id] int Yes The permanent list. If provided, the event specific list_id will be automatically set.
ticket[event_id] int Yes, if event_ticket_type_id is provided. The event to assign this ticket to.
ticket[ticket_type_id] int Yes, if event_ticket_type_id is provided. The ticket type to assign this ticket to.

Standalone ticket

{
  "ticket": {
    "name": "Jeff Blake"
    "email": "jeff@guestmanager.com"
    "event_ticket_type_id": 123456
    "dispatch": true
  }
}

Ticket belonging to guest

{
  "ticket": {
    "guest_id": 98433
    "event_ticket_type_id": 123456
    "dispatch": true
  }
}

Update a ticket

Request

PATCH
/tickets/{id}

Parameters

See parameters for create a ticket.

Delete a ticket

Request

DELETE
/tickets/{id}

Parameters

None.

Responses

Response properties

Example Response

{
    "id": 38133,
    "form_id": 3591,
    "answers": [{
            "id": 167286,
            "form_field_id": 10661,
            "value": "592",
            "human_value": "Miele Centre Staff",
            "field": {
                "id": 10661,
                "label": "How did you find out about the demonstration?",
                "required": true,
                "enabled": true,
                "help_text": "",
                "type": "multiple_choice",
                "options": [{
                        "id": 592,
                        "form_field_id": 10661,
                        "name": "Miele Centre Staff",
                        "value": "",
                        "type": null,
                        "position": 1
                    },
                    {
                        "id": 594,
                        "form_field_id": 10661,
                        "name": "Newspaper Ad",
                        "value": "",
                        "type": null,
                        "position": 3
                    },
                    {
                        "id": 790,
                        "form_field_id": 10661,
                        "name": "Friend Referral",
                        "value": "",
                        "type": null,
                        "position": 7
                    }
                ]
            }
        },
        {
            "id": 167287,
            "form_field_id": 10655,
            "value": "test",
            "human_value": "test",
            "field": {
                "id": 10655,
                "label": "When did you buy your appliance?",
                "required": true,
                "enabled": true,
                "help_text": "",
                "type": "text_field",
                "options": []
            }
        },
        {
            "id": 167288,
            "form_field_id": 10654,
            "value": "791",
            "human_value": "Other (list below)",
            "field": {
                "id": 10654,
                "label": "Which Miele appliance do you own?",
                "required": true,
                "enabled": true,
                "help_text": "",
                "type": "multiple_choice",
                "options": [{
                        "id": 791,
                        "form_field_id": 10654,
                        "name": "Other (list below)",
                        "value": "",
                        "type": null,
                        "position": 98
                    },
                    {
                        "id": 792,
                        "form_field_id": 10654,
                        "name": "My appliance isn't listed here",
                        "value": "",
                        "type": null,
                        "position": 99
                    },
                    {
                        "id": 529,
                        "form_field_id": 10654,
                        "name": "H 2661 B CleanSteel 60cm wide oven",
                        "value": "",
                        "type": null,
                        "position": null
                    }
                ]
            }
        },
        {
            "id": 167289,
            "form_field_id": 10775,
            "value": null,
            "human_value": null,
            "field": {
                "id": 10775,
                "label": "Other",
                "required": false,
                "enabled": true,
                "help_text": "",
                "type": "text_field",
                "options": []
            }
        }
    ]
}
Attribute Type Description
form_id integer The referenced Form read-only
answers array Individual answers contained in this response.

Answer attributes

Attribute Type Description
form_field_id integer The question being answered. read-only
value string array
human_value string If multiple_choice, the name of the option. read-only
field object The question. read-only

Field attributes

Attribute Type Description
type string The kind of question being asked. text_field, multiple_choice
label string Question being asked.
required boolean
enabled boolean
help_text string Additional information about the question.
options array If type is multiple_choice, these are the possible answers.

Option attributes

Attribute Type Description
form_field_id integer The kind of question being asked. text_field, multiple_choice
name string The option value/name.
position integer How to sort the option.

Payment Methods

Payment method properties

Attribute Type Description
type string
name string
description string
display_name string
currencies array A list of currencies this payment method supports.
billing_address_required boolean
payment_profiles_enabled boolean
test_mode boolean
active boolean
tokenize_key string If the gateway supports credit card tokenization, use this key to generate a token clientside before submitting to the API.

Addresses

Address properties

Attribute Type Description
address1 string Line 1.
address2 string Line 2.
city string City
zipcode string Zip code / postal code.
state_name string Name of the State.
state_code string Abbreviation of the State.
country_name string Name of the country.
country_code string ISO code of the Country.
state_id integer ID of state.
country_id integer ID of country.
state object State
country object Country

State properties

Attribute Type Description
name string Name of the state.
code string Abbreviation of the state name.
country_id integer The country this state is in.

Country properties

Attribute Type Description
name string Name of the country.
code string ISO code of the country.
currency_code string Currency ISO code.
phone_prefix string Phone prefix.

List countries

If you need to create address forms in your UI, it is recommended to use our maintained list of country data and ids.

GET
/countries

List country states

GET
/countries/{country-id}/states

Enterprise

The Enterprise API is only available for private label and reseller clients. These endpoints require an Enterprise API Key (different from the one described in the introduction). Please contact support to get your API key.

Base URL

Api Version URL
Latest https://app.guestmanager.com/api/public/enterprise
v1 https://app.guestmanager.com/api/public/enterprise/v1

Authentication

Please see the Authentication section under Topics.

Request

curl -X GET \
  https://app.guestmanager.com/api/public/enterprise/v1 \
  -H 'Authorization: Token abcedf123' \
  -H 'Content-Type: application/json'

Response

{
  "id": 0,
  "name": "Your enterprise name"
}

Using the API endpoints above

To use the API endpoints above on behalf of your company clients, you must use a company API Key (not your enterprise API key). You can get the company API key below when creating the company. Be sure to store this key somewhere in your database.

Create company

POST
/companies

Request parameters

Attribute Type Required Description
company[name] string yes Company name.
company[address_attributes][country_code] integer yes ISO code of the company's country.

Sample request

{
  "company": {
    "name": "New company",
    "address_attributes": {
      "country_code": "US"
    }
  }
}

Response

Sample response

{
  "name": "Company name",
  "password": "******",
  "pin": "1234"
  "api_key": "*******"
}