NAV Navbar

guestmanagerAPI Documentation

JSON
  • Introduction
  • Topics
  • Events
  • Ticket types
  • Ticket Tiers
  • Recurring events
  • Event Categories
  • Venues
  • Orders
  • Checkout
  • Tickets
  • Responses
  • Payment Methods
  • Addresses
  • Enterprise
  • 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 Header
    curl "http://app.guestmanager.com/api/pubic/v1"
      -H "Authorization: Token meowmeowmeow"
    

    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 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.

    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": "*******"
    }