NAV Navbar

guestmanagerAPI Documentation

cURL

Topics

Changelog

v2

Getting started

Tooling

Postman is a great app for testing and experimenting with our API. You can download it here: https://www.getpostman.com/

Base URL

Api Version URL
Latest (v2) https://app.guestmanager.com/api/public
v2 https://app.guestmanager.com/api/public/v2
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 1 minute period. If you need to handle more, please contact support. The Retry-After header will specify when you can continue making requests.

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 (Using Company API)

curl -X GET \
  https://app.guestmanager.com/api/public/v2 \
  -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

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. If the status code returned is in the 2xx range, you may assume the request succeeded. Therefore, rather than check if the JSON response has an error, always check the status code instead.

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 - check response for details and fix.
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 - check error details and correct.
429 Too Many Requests -- You're making too many requests.
500 Internal Server Error -- We had a problem with our server. Please contact support.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Exceptional errors

Exceptional errors indiciate a problem with your request 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",
                "name": null,
                "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 name.
name string If the relevant attribute is a relationship, we will add the name of that record here.
code string The type of validation error. See below for possibile codes.
message string A human readable version of the code
detail object Any extra attributes that may be useful, depending on the error.

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

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

Transformations

Images

Many resources have images attached them. By default we will only include the URL to the original, unaltered image that was uploaded into our system. You can also dynamically resize, alter, and transform images by specifying additional request parameters.

This is achieved by specifying an images request parameter in either GET endpoint (list collection, get individual resource)

Parameter Type Description
images[{resource_name}] object Which resource to target. This allows you to target relationships of an object as well.
images[{resource_name}][{field_name}] array Provide an array of transformations. A URL to the image will be returned for each.

Let's look at an example: requesting thumbnail images for event categories.

{
  "images": { # Top level request parameter
    "category": { # Specify which resource type
      "image": [ # Specify which `field` on the resource
        {
          "key": "my_thumbnail", # Name your key, this will be returned back to you
          "options": { # Specify image transformations
            "resize": "250x250>"
          }
        }
      ]
    }
  }
}

Transformation options

Parameter Type Description
resize string Resize the image. For complete reference, refer to ImageMagick reference
auto_orient boolean Attempts to auto-orient the image. For example, iOS selfies can typically benefit from this option.

We also support any options that ImageMagick supports. For a complete list of options, please see ImageMagick's Command line reference

Pagination

All requests to a GET collection endpoint are paginated. The default is 10 records per page, and the maximum is 100 per page. Some resources may have a per page limit (for example, 50 is the maximum for events).

Pagination request parameters

Parameter Default Description
page[number] 1 The page to return records for.
page[size] 10 How many records to return in each response.

Sample pagination response

{
  "data": [...],
  "meta": {
      "count": 10,
      "total": 14633,
      "page": {
          "number": 1,
          "size": 10,
          "next": 2,
          "prev": null,
          "total": 1464,
          "last": false,
          "first": true,
          "out_of_range": false
      },
      "links": {
          "self": ".../api/public/v2/events?page[number]=1",
          "next": ".../api/public/v2/events?page%5Bnumber%5D=2",
          "prev": null,
          "last": ".../api/public/v2/events?page%5Bnumber%5D=1464",
          "first": ".../api/public/v2/events?page%5Bnumber%5D=1"
      }
  }
}
* Note: Full URLs omitted for brevity

Pagination response meta data

All pagination information is returned in a meta key in the response. Please see example on the right.

For convenience, we include links to fetch the next, previous, first, and last pages. These links include your original request parameters, such as filter and sort

Parameter Type Description
meta[count] integer The number of records returned in this request.
meta[total] integer The total number of records, across all pages.
meta[page][number] integer The current page number.
meta[page][size] integer The page size.
meta[page][next] integer The next page number. null if no next page.
meta[page][prev] integer The previous page number. null if no previous page.
meta[page][total] integer Total number of pages.
meta[page][last] integer The last page number.
meta[page][first] integer The first page number.
meta[page][out_of_range] boolean true if the requested page number does not match any results.
meta[links][self] URL Original request URL.
meta[links][next] URL URL to retrieve next page of results. null if no next page.
meta[links][prev] URL URL to retrieve previous page of results. null if no previous page.
meta[links][last] URL URL of the last page of results.
meta[links][first] URL URL of the first page of results.

Filtering

Filtering responses

curl -X GET \
  http://app.guestmanager.test:3000/api/public/v2/events \
  -H 'Authorization: Token ....' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
        "ids": "1,2,3"
    }
}'

For GET requests to a collection, e.g. /events, you can filter data using the filter request parameter. More details on which fields can be filtered on are described in the relevant endpoint.

Parameter Format Example
filter[ids] Comma separated string or JSON array. "1,2,3" or json {"ids": [1,2,3]}
filter[created_at][from] date or datetime 2018-05-25
filter[created_at][to] date or datetime 2018-05-25

Sorting

Sorting responses

curl -X GET \
  http://app.guestmanager.test:3000/api/public/v2/events \
  -H 'Authorization: Token ....' \
  -H 'Content-Type: application/json' \
  -d '{
    "sort": {
        "starts_at": "asc"
    }
}'

For GET requests to a collection, e.g. /events, you can sort responses using the sort request parameter. More details on which fields can be sorted on are described in the relevant endpoint.

Parameter Value
sort[{field}] asc or desc

Where you replace {field} with the field to sort on, and specify the value as asc or desc. You may sort on multiple fields.

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 fields you are interested in for that particular resource.
include Comma separated string of the relationships you are interested in for that particular resource.

Lists of available fields and relationships are specified in the collection endpoints.

Events

See Objects section for details on the fields and relationships.

List events

GET
/events

List events (no parameters)

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

List events with registration types and price information, sorted by starts_at

curl -X GET \
  https://app.guestmanager.com/api/public/v2/events/ \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "include": "registration_types.prices",
    "sort": {
        "starts_at": "asc"
    }
}'

Response

{
    "data": [
        {
            "id": 59978,
            "name": "Gourmet Steam Oven",
            "slug": "gourmet-steam-oven-10-30am-12-00pm",
            "venue_id": 1989,
            "parent_event_id": 59918,
            "calendar_id": null,
            "published_at": "2016-10-17T01:08:42.038414Z",
            "start": {
                "tz": "Melbourne",
                "local": "2016-10-28T10:30:00+11:00",
                "utc": "2016-10-27T23:30:00Z"
            },
            "end": {
                "tz": "Melbourne",
                "local": "2016-10-28T12:00:00+11:00",
                "utc": "2016-10-28T01:00:00Z"
            },
            "registration_types": [
                {
                    "id": 24,
                    "variant_id": 1867,
                    "name": "General admission",
                    "description": null,
                    "prices": [
                        {
                            "decimal": "0.0",
                            "amount": 0,
                            "currency": "AUD",
                            "default": true,
                            "formatted": "$0.00"
                        }
                    ]
                }
            ]
        },
        ...
    ],
    "meta": {
        "count": 10,
        "total": 4602,
        "page": {
            "number": 1,
            "size": 10,
            "next": 2,
            "prev": null,
            "total": 461,
            "last": false,
            "first": true,
            "out_of_range": false
        },
        "links": {
            "self": "https://app.guestmanager.com/api/public/v2/events/",
            "next": "https://app.guestmanager.com/api/public/v2/events?include=registration_types.prices&page%5Bnumber%5D=2&sort%5Bstarts_at%5D=asc",
            "prev": null,
            "first": "https://app.guestmanager.com/api/public/v2/events?include=registration_types.prices&page%5Bnumber%5D=1&sort%5Bstarts_at%5D=asc",
            "last": "https://app.guestmanager.com/api/public/v2/events?include=registration_types.prices&page%5Bnumber%5D=461&sort%5Bstarts_at%5D=asc"
        }
    }
}

Request parameters

Parameter Type Required Default Description
page[size] integer no 10 How many records to return per request. Default is 10, maximum is 50
page[number] integer no 1 The page of records to request.
sort[{field}] string no none Replace {field} with one of id, name, starts_at, ends_at, and set the value to asc or desc. You may specify multiple sort fields.
fields string no id,name Comma separated list of attributes to return. See company object for possible fields.
include string no none Comma separated list of relationships to include.
filter[published] boolean no none true or false
filter[company_id] integer no none Filter by company.
filter[venue_id] integer no none Filter by venue.
filter[category_id] integer no none Filter by category.
filter[parent_event_id] integer no none Filter by recurring event.
filter[starts_at][from] date no none Filter events on or after this date. *
filter[starts_at][to] date no none Filter events before this date. *
filter[ends_at][from] date no none Filter events ending on or after this date. Generally, filtering by starts_at instead is more desirable.
filter[ends_at][to] date no none Filter events ending before this date. *
filter[status] string no none this_week, next_week, next_month, active, over, past, future, today, tomorrow
active: events in progress and future events
over: events where ends_at < current time
future: events with start dates in the future (excludes active events)
past: events where starts_at is less than current time
this_week: Monday-Sunday
next_week: Next Monday-Sunday

Fetch event

GET
/events/{id}

Fetch event

curl -X GET \
  https://app.guestmanager.com/api/public/v2/events/123456 \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \

Create event

POST
/events

Create event request

curl -X POST \
  http://app.guestmanager.com/api/public/v2/events/ \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "event": {
        "name": "New event",
        "starts_at": "2018-12-28T04:00:00Z",
        "ends_at": "2018-12-28T08:00:00Z",
        "venue_id": 2847
    }
}'

Create event response

{
    "id": 71390,
    "name": "New event",
    "slug": "new-event",
    "venue_id": 2847,
    "parent_event_id": null,
    "calendar_id": null,
    "published_at": null,
    "start": {
        "tz": "Central Time (US & Canada)",
        "local": "2018-12-27T22:00:00-06:00",
        "utc": "2018-12-28T04:00:00Z"
    },
    "end": {
        "tz": "Central Time (US & Canada)",
        "local": "2018-12-28T02:00:00-06:00",
        "utc": "2018-12-28T08:00:00Z"
    },
    "venue": {
        "id": 2847,
        "name": "Texas Motor Speedway",
        "description": null,
        "slug": "texas-motor-speedway"
    },
    "categories": [],
    "registration_types": [],
    "list": {
        "id": 1016744,
        "name": "RLL Hospitality",
        "slug": "rll-hospitality",
        "status": "visible",
        "permanent_list_id": 27236,
        "image": null
    }
}

Request parameters

Parameter 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[starts_at] datetime yes Start date and time of the event. Provide UTC iso8601 string
event[ends_at] datetime yes End date and time of the event. Provide UTC iso8601 string
event[published_at] datetime no Set this to any date to publish the event.

Update event

PATCH
/events/{event-id}

Update event

curl -X PATCH \
  https://app.guestmanager.com/api/public/v2/events/71383 \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "event": {
        "name": "New name"
    }
}'

Request parameters

See parameters for the create event endpoint.

Add ticket type

Add an existing ticket type to this event.

POST
/events/{event-id}/ticket_types/add

Add existing ticket type

curl -X POST \
  https://app.guestmanager.com/api/public/v2/events/71389/ticket_types/add \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "ticket_type_id": 2217
}'

Response

{
    "id": 19056,
    "created_at": "2019-01-07T21:46:39.605652Z",
    "updated_at": "2019-01-07T21:46:39.605652Z",
    "ticket_type_id": 2217,
    "event_id": 71389,
    "starts_at": null,
    "ends_at": null,
    "pdf_template_id": null,
    "ticket_type": {
        "id": 2217,
        "created_at": "2016-10-17T00:51:35.291358Z",
        "updated_at": "2019-01-07T21:46:39.619151Z",
        "archived_at": null,
        "name": "Free Discovery Product Demonstrations",
        "pdf_template_id": 704,
        "wallet_template_id": null,
        "attachable": true,
        "transferable": false,
        "include_name": true,
        "include_email": true,
        "require_name": true,
        "require_email": false,
        "enforce_barcode_pool": false,
        "attachment_name": "{{ticket.name}}"
    }
}

Request parameters

Parameter Type Required Description
ticket_type_id int yes ID of the ticket type to add to this event.

Create new ticket type

Create a new ticket type and add it to an event, all in one step. It is advised that you do not duplicate ticket type names, therefore it is recommended to find or create the ticket type separately, and then add it to the event using the above endpoint.s

POST
/events/{event-id}/ticket_types

Create basic ticket type and add it to event

curl -X POST \
  https://app.guestmanager.com/api/public/v2/events/71389/ticket_types/ \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "ticket_type": {
        "name": "GA"
    }
}'

Response

{
    "id": 19057,
    "created_at": "2019-01-07T21:56:42.769762Z",
    "updated_at": "2019-01-07T21:56:42.769762Z",
    "ticket_type_id": 7456,
    "event_id": 71389,
    "starts_at": null,
    "ends_at": null,
    "pdf_template_id": null,
    "ticket_type": {
        "id": 7456,
        "created_at": "2019-01-07T21:56:42.755038Z",
        "updated_at": "2019-01-07T21:56:42.774215Z",
        "archived_at": null,
        "name": "GA",
        "pdf_template_id": null,
        "wallet_template_id": null,
        "attachable": true,
        "transferable": true,
        "include_name": false,
        "include_email": false,
        "require_name": false,
        "require_email": false,
        "enforce_barcode_pool": false,
        "attachment_name": "{{ticket.name}}"
    }
}

Request parameters

Parameter Type Required Default Description
ticket_type[name] string yes Name of the ticket type.
ticket_type[display_name] string no Display name.
ticket_type[pdf_template_id] string no null Ticket design template ID.
ticket_type[wallet_template_id] string no null Apple Wallet design template ID.
ticket_type[attachable] boolean no true true to include ticket as a PDF attachment, false to include as a download link instead.
ticket_type[transferable] boolean no true Whether guests can transfer their ticket to someone else.
ticket_type[include_name] boolean no false See object reference.
ticket_type[require_name] boolean no false See object reference.
ticket_type[include_email] boolean no false See object reference.
ticket_type[require_email] boolean no false See object reference.
ticket_type[enforce_barcode_pool] boolean no false See object reference.

List event lists

GET
/events/{event-id}/lists

Fetch event lists

curl -X GET \
  'https://app.guestmanager.com/api/public/v2/events/12345/lists' \
  -H 'Authorization: Token abcedfg' \
  -H 'Content-Type: application/json' \

Response

{
    "data": [
        {
            "id": 1014210,
            "name": "RLL Hospitality",
            "slug": "rll-hospitality",
            "status": "visible",
            "permanent_list_id": 27236,
            "image": null,
            "permanent_list": {
                "id": 27236,
                "name": "RLL Hospitality",
                "slug": "rll-hospitality",
                "recurring": true,
                "status": "hidden"
            }
        },
        ...
    ],
    "meta": {
        "count": 10,
        "total": 24,
        "page": {
            "number": 1,
            "size": 10,
            "next": 2,
            "prev": null,
            "total": 3,
            "last": false,
            "first": true,
            "out_of_range": false
        },
        "links": {
            "self": "https://app.guestmanager.com/api/public/v2/events/70962/lists?include=permanent_list",
            "next": "https://app.guestmanager.com/api/public/v2/events/70962/lists?include=permanent_list&page%5Bnumber%5D=2",
            "prev": null,
            "first": "https://app.guestmanager.com/api/public/v2/events/70962/lists?include=permanent_list&page%5Bnumber%5D=1",
            "last": "https://app.guestmanager.com/api/public/v2/events/70962/lists?include=permanent_list&page%5Bnumber%5D=3"
        }
    }
}

Request parameters

Parameter Type Required Default Description
page[size] integer no 10 How many records to return per request. Default is 10, maximum is 100
page[number] integer no 1 The page of records to request.
sort[{field}] string no none The field to sort results by. Can be id, name, with value asc or desc
fields string no all Comma separated list of attributes to return.
include string no Relationships to include.
images[list][image] object no Customize the image (resize, etc). See Topics for details.

Create event list

POST
/events/{event-id}/lists

Create event list

curl -X POST \
  https://app.guestmanager.com/api/public/v2/events/71339/lists \
  -H 'Accept: application/json' \
  -H 'Authorization: Token abcdefg' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'list[image]=@/path/to/file/image.png' \
  -F 'list[name]=New list' \
  -F 'list[description]=blah blah'

Response

{
    "id": 1018378,
    "name": "New list",
    "description": "blah blah",
    "slug": "new-list-5839e45b-27ee-49f4-9de6-85d285b75191",
    "status": "visible",
    "permanent_list_id": null,
    "image": {
        "original": "https://app.guestmanager.com/....png"
    },
    "permanent_list": null,
    "setting": {
        "description": "<p>...</p>",
        "image": {
            "original": "https://app.guestmanager.com/...jpg"
        }
    }
}

Request parameters

Parameter Type Required Description
list[name] string yes Name of the list.
list[image] multipart no If providing an image, the API request must be in multipart. Only submit JPG images, or non-interlaced PNGs.
list[description] string no Describe the list. This content can be dynamically inserted onto a ticket.

Update event list

PATCH
/events/{event-id}/lists/{id}

Update event list

curl -X PATCH \
  https://app.guestmanager.com/api/public/v2/events/71339/lists/1018382 \
  -H 'Accept: application/json' \
  -H 'Authorization: Token abcdef' \
  -H 'Content-Type: application/json' \
  -d '{
    "list": {
        "name": "new name"
    }
}'

Request parameters

See parameters for creating a list.

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.

See Objects section for details on the fields and relationships.

List ticket types

GET
/ticket_types

List ticket types

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

Response

{
    "data": [
        {
            "id": 4104,
            "created_at": "2018-03-27T04:37:10.171834Z",
            "updated_at": "2019-01-02T23:07:04.834997Z",
            "archived_at": null,
            "name": "GA",
            "pdf_template_id": 8355,
            "wallet_template_id": null,
            "attachable": true,
            "transferable": true,
            "include_name": false,
            "include_email": false,
            "require_name": false,
            "require_email": false,
            "enforce_barcode_pool": false,
            "attachment_name": "{{ticket.name}}"
        },
        ...
    ],
    "meta": {
        "count": 5,
        "total": 5,
        "page": {
            "number": 1,
            "size": 10,
            "next": null,
            "prev": null,
            "total": 1,
            "last": true,
            "first": true,
            "out_of_range": false
        },
        "links": {
            "self": "https://app.guestmanager.com/api/public/v2/ticket_types",
            "next": null,
            "prev": null,
            "first": "https://app.guestmanager.com/api/public/v2/ticket_types?page%5Bnumber%5D=1",
            "last": "https://app.guestmanager.com/api/public/v2/ticket_types?page%5Bnumber%5D=1"
        }
    }
}

Request parameters

Parameter Type Required Default Description
page[size] integer no 10 How many records to return per request. Default is 10, maximum is 100
page[number] integer no 1 The page of records to request.
sort[{field}] string no none Replace {field} with one of id, created_at, updated_at, name, and set the value to asc or desc. You may specify multiple sort fields.
fields string no all Comma separated list of attributes to return.
include string no none Relationships to include.

Create ticket type

POST
/ticket_types

Create basic ticket type and add it to event

curl -X POST \
  https://app.guestmanager.com/api/public/v2/ticket_types/ \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "ticket_type": {
        "name": "GA"
    }
}'

Response

{
  "id": 7456,
  "created_at": "2019-01-07T21:56:42.755038Z",
  "updated_at": "2019-01-07T21:56:42.774215Z",
  "archived_at": null,
  "name": "GA",
  "pdf_template_id": null,
  "wallet_template_id": null,
  "attachable": true,
  "transferable": true,
  "include_name": false,
  "include_email": false,
  "require_name": false,
  "require_email": false,
  "enforce_barcode_pool": false,
  "attachment_name": "{{ticket.name}}"
}

Request parameters

Parameter Type Required Default Description
ticket_type[name] string yes Name of the ticket type.
ticket_type[display_name] string no Display name.
ticket_type[pdf_template_id] string no null Ticket design template ID.
ticket_type[wallet_template_id] string no null Apple Wallet design template ID.
ticket_type[attachable] boolean no true true to include ticket as a PDF attachment, false to include as a download link instead.
ticket_type[transferable] boolean no true Whether guests can transfer their ticket to someone else.
ticket_type[include_name] boolean no false See object reference.
ticket_type[require_name] boolean no false See object reference.
ticket_type[include_email] boolean no false See object reference.
ticket_type[require_email] boolean no false See object reference.
ticket_type[enforce_barcode_pool] boolean no false See object reference.

Fetch ticket type

GET
/ticket_types/{id}

Fetch ticket type

curl -X GET \
  https://app.guestmanager.com/api/public/v2/ticket_types/7456 \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \

Response

{
    "id": 7456,
    "created_at": "2019-01-07T21:56:42.755038Z",
    "updated_at": "2019-01-07T21:56:43.048201Z",
    "archived_at": null,
    "name": "GA",
    "display_name": null,
    "pdf_template_id": null,
    "wallet_template_id": null,
    "attachable": true,
    "transferable": true,
    "include_name": false,
    "include_email": false,
    "require_name": false,
    "require_email": false,
    "enforce_barcode_pool": false,
    "attachment_name": "{{ticket.name}}"
}

Request parameters

None.

Update ticket type

PATCH
/ticket_types/{id}

Update ticket type

curl -X PATCH \
  https://app.guestmanager.com/api/public/v2/ticket_types/7456 \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "ticket_type": {
        "name": "New name"
    }
}'

Request parameters

See parameters in create ticket type endpoint.

Delete ticket type

DELETE
/ticket_types/{id}

Delete ticket type

curl -X DELETE \
  https://app.guestmanager.com/api/public/v2/ticket_types/7456 \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \

Response (204) No Content

Request parameters

None.

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.

See Objects section for details on the fields and relationships.

List recurring events

GET
/recurring_events

List recurring events

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

Response

{
    "data": [
        {
            "id": 69956,
            "name": "Girls' Night In",
            "slug": "girls-night-in",
            "calendar_id": null,
            "position": 1
        },
        {
            "id": 69929,
            "name": "Father's Day Roast",
            "slug": "father-s-day-roast",
            "calendar_id": null,
            "position": 1
        },
        ...
    ],
    "meta": {
        "count": 10,
        "total": 37,
        "page": {
            "number": 1,
            "size": 10,
            "next": 2,
            "prev": null,
            "total": 4,
            "last": false,
            "first": true,
            "out_of_range": false
        },
        "links": {
            "self": "https://app.guestmanager.com/api/public/v2/recurring_events",
            "next": "https://app.guestmanager.com/api/public/v2/recurring_events?page%5Bnumber%5D=2",
            "prev": null,
            "first": "https://app.guestmanager.com/api/public/v2/recurring_events?page%5Bnumber%5D=1",
            "last": "https://app.guestmanager.com/api/public/v2/recurring_events?page%5Bnumber%5D=4"
        }
    }
}

Request parameters

Parameter Type Required Default Description
page[size] integer no 10 How many records to return per request. Default is 10, maximum is 50
page[number] integer no 1 The page of records to request.
sort[{field}] string no none Replace {field} with one of id, created_at, updated_at, position, and set the value to asc or desc. You may specify multiple sort fields.
fields string no all Comma separated list of attributes to return.
include string no none Relationships to include.
filter[published_at] string no none Values: published, unpublished

Event categories

An event can have many categories. See Objects section for details on the fields and relationships.

List categories

GET
/categories

List categories

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

Response

{
    "data": [
        {
            "id": 18,
            "name": "MasterClasses",
            "subtitle": null,
            "position": 3,
            "short_description": null,
            "description": null,
            "image": {
                "original": "../image.png"
            }
        },
        {
            "id": 3,
            "name": "Complimentary Owner Product Demonstrations",
            "subtitle": "Master Your Miele",
            "position": 2,
            "short_description": "text",
            "description": "HTML description",
            "image": null
        }
    ],
    "meta": {
        "count": 3,
        "total": 3,
        "page": {
            "number": 1,
            "size": 10,
            "next": null,
            "prev": null,
            "total": 1,
            "last": true,
            "first": true,
            "out_of_range": false
        },
        "links": {
            "self": "https://app.guestmanager.com/api/public/v2/categories",
            "next": null,
            "prev": null,
            "first": "https://app.guestmanager.com/api/public/v2/categories?page%5Bnumber%5D=1",
            "last": "https://app.guestmanager.com/api/public/v2/categories?page%5Bnumber%5D=1"
        }
    }
}

List categories with image resized

curl -X GET \
  https://app.guestmanager.com/api/public/v2/categories \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "images": {
        "category": {
            "image": [
                {
                    "key": "thumbnail",
                    "options": {
                        "resize": "250x250>"
                    }
                }
            ]
        }
    }
}'

Response (details omitted for brevity)

{
    "data": [
        {
            "id": 18,
            "name": "MasterClasses",
            "subtitle": null,
            "position": 3,
            "short_description": null,
            "description": null,
            "image": {
                "original": "https://app.guestmanager.com/rails/active_storage/blobs/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBdndEIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--529b75c541f8b17666f9c0ec4510720254d824a3/event_portrait.png",
                "thumbnail": "https://app.guestmanager.com/rails/active_storage/representations/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBdndEIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--529b75c541f8b17666f9c0ec4510720254d824a3/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHZPaUZCWTNScGIyNURiMjUwY205c2JHVnlPanBRWVhKaGJXVjBaWEp6QnpvUVFIQmhjbUZ0WlhSbGNuTkRPaTFCWTNScGRtVlRkWEJ3YjNKME9qcElZWE5vVjJsMGFFbHVaR2xtWm1WeVpXNTBRV05qWlhOemV3WkpJZ3R5WlhOcGVtVUdPZ1pGUmtraURUSTFNSGd5TlRBK0Jqc0lWRG9QUUhCbGNtMXBkSFJsWkZRPSIsImV4cCI6bnVsbCwicHVyIjoidmFyaWF0aW9uIn19--97d9c524c32e1915e2f7cbf4eceb89a17ca810fc/event_portrait.png"
            }
        }
    ],
    "meta": ...
}

Request parameters

Parameter Type Required Default Description
page[size] integer no 10 How many records to return per request. Default is 10, maximum is 100
page[number] integer no 1 The page of records to request.
sort[{field}] object no Replace {field} with one of position, with value of asc or desc
images[category][image] array no Request custom sized images. See Topics for details.

Venues

See Objects section for details on the fields and relationships.

List venues

GET
/venues

List venues with addresses

curl -X GET \
  'https://app.guestmanager.com/api/public/v2/venues?include=address' \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \

Response

{
    "data": [...],
    "meta": {
        "count": 8,
        "total": 8,
        "page": {
            "number": 1,
            "size": 10,
            "next": null,
            "prev": null,
            "total": 1,
            "last": true,
            "first": true,
            "out_of_range": false
        },
        "links": {
            "self": ".../api/public/v2/venues?include=address",
            "next": null,
            "prev": null,
            "last": ".../api/public/v2/venues?include=address&page%5Bnumber%5D=1",
            "first": ".../api/public/v2/venues?include=address&page%5Bnumber%5D=1"
        }
    }
}

Request parameters

Parameter Type Required Default Description
page[size] integer no 10 How many records to return per request. Default is 10, maximum is 100
page[number] integer no 1 The page of records to request.
sort[{field}] string no none Replace {field} with one of id, created_at, updated_at, name, and set the value to asc or desc. You may specify multiple sort fields.
fields string no id,name Comma separated list of attributes to return.
include string no none Relationships to include. See Venue object for possible relationships.

Create venue

POST
/venues

Create venue (minimum parameters)

curl -X POST \
  https://app.guestmanager.com/api/public/v2/venues \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "venue": {
        "name": "The Rio Theatre",
        "time_zone": "Pacific Time (US & Canada)"
    }
}'

Response

{
    "id": 3245,
    "name": "The Rio Theatre",
    "description": null,
    "slug": "the-rio-theatre",
    "created_at": "2019-01-07T20:33:44.583012Z",
    "updated_at": "2019-01-07T20:33:44.583012Z",
    "time_zone": "Pacific Time (US & Canada)",
    "tzinfo": {
        "name": "Pacific Time (US & Canada)",
        "identifier": "America/Los_Angeles",
        "offset": -28800,
        "formatted_offset": "-08:00"
    },
    "address": null
}

Create venue (utilizing all parameters)

curl -X POST \
  https://app.guestmanager.com/api/public/v2/venues \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "venue": {
        "name": "The Rio Theatre",
        "description": "its around the corner",
        "time_zone": "Pacific Time (US & Canada)",
        "address": {
            "address1": "123 Main st",
            "city": "Vancouver",
            "zipcode": "V6T2J3",
            "country_code": "CA",
            "state_code": "BC"
        }
    }
}'

Response

{
    "id": 3246,
    "name": "The Rio Theatre",
    "description": "its around the corner",
    "slug": "the-rio-theatre-7ea12f80-35c0-4599-bdfc-3ef7c7e9f658",
    "created_at": "2019-01-07T20:35:48.650021Z",
    "updated_at": "2019-01-07T20:35:48.650021Z",
    "time_zone": "Pacific Time (US & Canada)",
    "tzinfo": {
        "name": "Pacific Time (US & Canada)",
        "identifier": "America/Los_Angeles",
        "offset": -28800,
        "formatted_offset": "-08:00"
    },
    "address": {
        "id": 144350,
        "address1": "123 Main st",
        "city": "Vancouver",
        "zipcode": "V6T2J3",
        "state_name": "British Columbia",
        "state_code": "BC",
        "country_name": "Canada",
        "country_code": "CA"
    }
}

Parameters

Parameter Type Required Description
venue[name] string Yes Name of the venue.
venue[description] string No Any additional details about the venue.
venue[time_zone] string Yes Time zone. See Object reference for list of time zones.
venue[address] object No Venue address. See Object reference for parameters.

Orders

See Objects section for details on the fields and relationships.

Create an order

POST
/orders

Request parameters

Create empty order

curl -X POST \
  https://app.guestmanager.com/api/public/v2/orders \
  -H 'Accept: application/json' \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "order": {
        "currency": "USD",
        "guest_checkout": true
    }
}'

Empty order response

{
    "id": 214890,
    "number": "GMH3P6G79VRKQJ",
    "currency": "USD",
    "state": "cart",
    "checkout_steps": [
        "address",
        "complete"
    ],
    "item_count": 0,
    "contact_id": null,
    "guest_token": "9b96188212222b3c1283bd3dc3ac9de0",
    "guest_checkout": true,
    "first_name": null,
    "last_name": null,
    "email": null,
    "phone_number": null,
    "phone_number_country": null,
    "completed_at": null,
    "expires_at": "2019-01-10T19:44:39.781909Z",
    "total": {
        "decimal": "0.0",
        "amount": 0,
        "formatted": "$0.00"
    },
    "item_total": {
        "decimal": "0.0",
        "amount": 0,
        "formatted": "$0.00"
    },
    "adjustment_total": {
        "decimal": "0.0",
        "amount": 0,
        "formatted": "$0.00"
    },
    "promo_total": {
        "decimal": "0.0",
        "amount": 0,
        "formatted": "$0.00"
    },
    "bill_address": null,
    "ship_address": null,
    "line_items": [],
    "adjustments": [],
    "promotions": [],
    "tickets": [],
    "payments": [],
    "responses": []
}

Order with line items request

curl -X POST \
  https://app.guestmanager.com/api/public/v2/orders \
  -H 'Accept: application/json' \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "order": {
        "currency": "AUD",
        "guest_checkout": true,
        "first_name": "Jeff",
        "last_name": "Blake",
        "email": "jeff@gmail.com",
        "phone_number": "12068423456",
        "phone_number_country": "US",
        "line_items": [
            {
                "variant_id": 10542,
                "quantity": 2
            }
        ]
    }
}'

Order with line items response

{
    "id": 214893,
    "number": "GMMAFBD17KIOGT",
    "currency": "AUD",
    "state": "cart",
    "checkout_steps": [
        "tickets",
        "address",
        "payment",
        "complete"
    ],
    "item_count": 2,
    "contact_id": 1390001,
    "guest_token": "487b26211c9f9d8584abfdbadedd42e5",
    "guest_checkout": true,
    "first_name": "Jeff",
    "last_name": "Blake",
    "email": "jeff@gmail.com",
    "phone_number": "+12068423456",
    "phone_number_country": "US",
    "completed_at": null,
    "expires_at": "2019-01-10T20:56:29.296919Z",
    "total": {
        "decimal": "32.9",
        "amount": 3290,
        "formatted": "$32.90"
    },
    "item_total": {
        "decimal": "30.0",
        "amount": 3000,
        "formatted": "$30.00"
    },
    "adjustment_total": {
        "decimal": "2.9",
        "amount": 290,
        "formatted": "$2.90"
    },
    "promo_total": {
        "decimal": "0.0",
        "amount": 0,
        "formatted": "$0.00"
    },
    "bill_address": null,
    "ship_address": null,
    "line_items": [
        {
            "id": 222986,
            "order_id": 214893,
            "name": "Sell tix",
            "description": null,
            "variant_id": 10542,
            "quantity": 2,
            "currency": "AUD",
            "bundle_item_id": null,
            "price": {
                "decimal": "15.0",
                "amount": 1500,
                "formatted": "$15.00"
            },
            "subtotal": {
                "decimal": "30.0",
                "amount": 3000,
                "formatted": "$30.00"
            }
        }
    ],
    "adjustments": [
        {
            "id": 405427,
            "label": "Service Fee",
            "order_id": 214893,
            "adjustable_id": 222986,
            "adjustable_type": "LineItem",
            "source_id": 4946,
            "source_type": "ServiceFeeRate",
            "included": false,
            "mandatory": true,
            "eligible": true,
            "groupable": true,
            "finalized": false,
            "amount": {
                "decimal": "2.9",
                "amount": 290,
                "formatted": "$2.90"
            }
        }
    ],
    "promotions": [],
    "tickets": [
        {
            "id": 2596875,
            "number": "pucAP3KTv2d5TSurWhoE6GYb",
            "status": "pending",
            "name": null,
            "email": null,
            "barcode": "3146643903544781",
            "note": null,
            "event_id": 71615,
            "ticket_type_id": 2470,
            "event_ticket_type_id": 19503,
            "list_id": 1017266,
            "contact_id": 1390001,
            "dispatched_at": null,
            "downloaded_at": null,
            "checkin_at": null,
            "source_type": "line_item",
            "source_id": 222986,
            "links": {
                "pdf": null,
                "wallet": null
            }
        },
        {
            "id": 2596874,
            "number": "QHNLGkMVdQMH676q8kxtuNBL",
            "status": "pending",
            "name": null,
            "email": null,
            "barcode": "5127459989750870",
            "note": null,
            "event_id": 71615,
            "ticket_type_id": 2470,
            "event_ticket_type_id": 19503,
            "list_id": 1017266,
            "contact_id": 1390001,
            "dispatched_at": null,
            "downloaded_at": null,
            "checkin_at": null,
            "source_type": "line_item",
            "source_id": 222986,
            "links": {
                "pdf": null,
                "wallet": null
            }
        }
    ],
    "payments": [],
    "responses": []
}
Parameter Type Required Default Description
transition_order boolean no Advance the order to the first checkout step.
order[currency] string yes ISO code, e.g. CAD, USD, AUD, GBP
order[email] string no* Email of the purchaser.
order[guest_checkout] boolean yes Guest checkout mode must be enabled for all API orders.
order[first_name] string no* First name of purchaser.
order[last_name] string no* Last name of purchaser.
order[phone_number] string no Phone number of purchaser. Number is validated accordingly to phone_number_country
order[phone_number_country] string if phone_number provided ISO country code of the phone number, e.g. US, AU, CA
order[line_items] array no* Array of line items. Each line item must contain variant_id, and quantity

Response

Error

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.

Fetch order

GET
/orders/{id}

Fetch order request

curl -X GET \
  https://app.guestmanager.com/api/public/v2/orders/214894 \
  -H 'Accept: application/json' \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "guest_token": "752b3a667b53068433edc796848c1345"
}'
Parameter Type Required Default Description
guest_token string yes Provide the guest_token given to you in the create order endpoint.
fields string no Request a subset of the order attributes if desired.
include string no Request specific relationships.

Update order

Updates an order. If updating existing line_items, you must provide the id of each line item, as shown in the example at the right.

PATCH
/orders/{id}

Update line item quantity

curl -X PATCH \
  https://app.guestmanager.com/api/public/v2/orders/214894 \
  -H 'Accept: application/json' \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "guest_token": "752b3a667b53068433edc796848c1345",
    "order": {
        "line_items": [
            {
                "id": 222987,
                "quantity": 1
            }
        ]
    }
}'

Update line item response

{
    "id": 214894,
    "number": "GMBIU2EZ7K9D46",
    "currency": "AUD",
    "state": "cart",
    "checkout_steps": [
        "tickets",
        "address",
        "form",
        "payment",
        "complete"
    ],
    "item_count": 1,
    "contact_id": 1390001,
    "guest_token": "752b3a667b53068433edc796848c1345",
    "guest_checkout": true,
    "first_name": "Jeff",
    "last_name": "Blake",
    "email": "jeff@gmail.com",
    "phone_number": "+12068423456",
    "phone_number_country": "US",
    "completed_at": null,
    "expires_at": "2019-01-10T20:59:20.537628Z",
    "total": {
        "decimal": "16.45",
        "amount": 1645,
        "formatted": "$16.45"
    },
    "item_total": {
        "decimal": "15.0",
        "amount": 1500,
        "formatted": "$15.00"
    },
    "adjustment_total": {
        "decimal": "1.45",
        "amount": 145,
        "formatted": "$1.45"
    },
    "promo_total": {
        "decimal": "0.0",
        "amount": 0,
        "formatted": "$0.00"
    },
    "bill_address": null,
    "ship_address": null,
    "line_items": [
        {
            "id": 222987,
            "order_id": 214894,
            "name": "Sell tix",
            "description": null,
            "variant_id": 10542,
            "quantity": 1,
            "currency": "AUD",
            "bundle_item_id": null,
            "price": {
                "decimal": "15.0",
                "amount": 1500,
                "formatted": "$15.00"
            },
            "subtotal": {
                "decimal": "15.0",
                "amount": 1500,
                "formatted": "$15.00"
            }
        }
    ],
    "adjustments": [
        {
            "id": 405428,
            "label": "Service Fee",
            "order_id": 214894,
            "adjustable_id": 222987,
            "adjustable_type": "LineItem",
            "source_id": 4946,
            "source_type": "ServiceFeeRate",
            "included": false,
            "mandatory": true,
            "eligible": true,
            "groupable": true,
            "finalized": false,
            "amount": {
                "decimal": "1.45",
                "amount": 145,
                "formatted": "$1.45"
            }
        }
    ],
    "promotions": [],
    "tickets": [
        {
            "id": 2596876,
            "number": "V7DGKDb4BRZMc5tpcCsawJGx",
            "status": "pending",
            "name": null,
            "email": null,
            "barcode": "4818716329830908",
            "note": null,
            "event_id": 71615,
            "ticket_type_id": 2470,
            "event_ticket_type_id": 19503,
            "list_id": 1017266,
            "contact_id": 1390001,
            "dispatched_at": null,
            "downloaded_at": null,
            "checkin_at": null,
            "source_type": "line_item",
            "source_id": 222987,
            "links": {
                "pdf": null,
                "wallet": null
            }
        }
    ],
    "payments": [],
    "responses": [
        {
            "id": 52690,
            "form_id": 3587
        }
    ]
}

Request parameters

See create order endpoint for complete list of request parameters.

Parameter Required Description
guest_token yes Provide the order's guest_token to authorize updates to this order.

Response

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)
guest_checkout_required Orders created through the API must be in guest_checkout mode.

Void order

Incomplete orders, non-voided orders, and completed orders that do not have a credit card payment on them may be voided. Completed orders with cash or check payments applied may be voided.

PATCH
/orders/{id}/void

Void order request

curl -X PATCH \
  https://app.guestmanager.com/api/public/v2/orders/214894/void \
  -H 'Accept: application/json' \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
}'

Void order response (details omitted)

{
    "id": 214894,
    "number": "GMBIU2EZ7K9D46",
    "state": "voided",
    ...
}

Request parameters

None required

Apply coupon code

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

PATCH
/orders/{id}/apply_coupon_code

Apply coupon code request

curl -X PATCH \
  https://app.guestmanager.com/api/public/v2/orders/214894/apply_coupon_code \
  -H 'Accept: application/json' \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "guest_token": "752b3a667b53068433edc796848c1345",
    "coupon_code": "20off"
}'

Apply coupon code response

{
    "id": 214895,
    "number": "GMIZAJD7EKOQUX",
    "currency": "AUD",
    "state": "cart",
    "checkout_steps": [
        "tickets",
        "address",
        "form",
        "payment",
        "complete"
    ],
    "item_count": 2,
    "contact_id": 1390001,
    "guest_token": "af73d05bd847d66b62c21e56661c7069",
    "guest_checkout": true,
    "first_name": "Jeff",
    "last_name": "Blake",
    "email": "jeff@gmail.com",
    "phone_number": "+12068423456",
    "phone_number_country": "US",
    "completed_at": null,
    "expires_at": "2019-01-10T23:08:28.081445Z",
    "total": {
        "decimal": "26.72",
        "amount": 2672,
        "formatted": "$26.72"
    },
    "item_total": {
        "decimal": "30.0",
        "amount": 3000,
        "formatted": "$30.00"
    },
    "adjustment_total": {
        "decimal": "-3.28",
        "amount": -328,
        "formatted": "$-3.28"
    },
    "promo_total": {
        "decimal": "-6.0",
        "amount": -600,
        "formatted": "$-6.00"
    },
    "bill_address": null,
    "ship_address": null,
    "line_items": [
        {
            "id": 222988,
            "order_id": 214895,
            "name": "Sell tix",
            "description": null,
            "variant_id": 10542,
            "quantity": 2,
            "currency": "AUD",
            "bundle_item_id": null,
            "price": {
                "decimal": "15.0",
                "amount": 1500,
                "formatted": "$15.00"
            },
            "subtotal": {
                "decimal": "30.0",
                "amount": 3000,
                "formatted": "$30.00"
            }
        }
    ],
    "adjustments": [
        {
            "id": 405431,
            "label": "Promotion",
            "order_id": 214895,
            "adjustable_id": 222988,
            "adjustable_type": "LineItem",
            "source_id": 329,
            "source_type": "PromotionAction",
            "included": false,
            "mandatory": true,
            "eligible": true,
            "groupable": true,
            "finalized": false,
            "amount": {
                "decimal": "-6.0",
                "amount": -600,
                "formatted": "$-6.00"
            }
        },
        {
            "id": 405430,
            "label": "Service Fee",
            "order_id": 214895,
            "adjustable_id": 222988,
            "adjustable_type": "LineItem",
            "source_id": 4946,
            "source_type": "ServiceFeeRate",
            "included": false,
            "mandatory": true,
            "eligible": true,
            "groupable": true,
            "finalized": false,
            "amount": {
                "decimal": "2.72",
                "amount": 272,
                "formatted": "$2.72"
            }
        }
    ],
    "promotions": [
        {
            "id": 9185,
            "promotion_id": 301,
            "code": null
        }
    ],
    "tickets": [
        {
            "id": 2596879,
            "number": "DRHTvauq8N3Ay7ERFh7TUsmW",
            "status": "pending",
            "name": null,
            "email": null,
            "barcode": "2395309216989206",
            "note": null,
            "event_id": 71615,
            "ticket_type_id": 2470,
            "event_ticket_type_id": 19503,
            "list_id": 1017266,
            "contact_id": 1390001,
            "dispatched_at": null,
            "downloaded_at": null,
            "checkin_at": null,
            "source_type": "line_item",
            "source_id": 222988,
            "links": {
                "pdf": null,
                "wallet": null
            }
        },
        {
            "id": 2596878,
            "number": "nKUcCduXxmXN9DoYtsDnJqt4",
            "status": "pending",
            "name": null,
            "email": null,
            "barcode": "2208377212609034",
            "note": null,
            "event_id": 71615,
            "ticket_type_id": 2470,
            "event_ticket_type_id": 19503,
            "list_id": 1017266,
            "contact_id": 1390001,
            "dispatched_at": null,
            "downloaded_at": null,
            "checkin_at": null,
            "source_type": "line_item",
            "source_id": 222988,
            "links": {
                "pdf": null,
                "wallet": null
            }
        }
    ],
    "payments": [],
    "responses": [
        {
            "id": 52691,
            "form_id": 3587
        }
    ]
}

Sample error response (Status 422)

{
    "type": "validation_error",
    "message": "Coupon code already applied to order",
    "model": "Order",
    "id": 214894,
    "errors": {
        "attributes": [
            {
                "attribute": "coupon_code",
                "label": "Coupon code",
                "code": "already_applied",
                "message": "already applied to order",
                "detail": {}
            }
        ],
        "associations": {
            "tickets": {},
            "form_responses": {},
            "line_items": {}
        }
    }
}

Request parameters

Parameter Type Required Description
coupon_code string yes Optional if your account is not enabled for multi-currency.
guest_token string yes 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, adjustment_total, promotions, and adjustments on the Order for details.
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. This is an additive operation, i.e., if the order already contains 1 of the variant_id, and you add 2 more, the relevant line_item quantity will be updated to 3.

This is a convenience endpoint as you do not need to submit the correct line_item_id parameter.

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

Add variant to order

curl -X POST \
  https://app.guestmanager.com/api/public/v2/orders/214895/line_items/add \
  -H 'Accept: application/json' \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "guest_token": "af73d05bd847d66b62c21e56661c7069",
    "variant_id": 10542,
    "quantity": 1
}'

Response

{
    "id": 214895,
    "number": "GMIZAJD7EKOQUX",
    "currency": "AUD",
    "state": "cart",
    "checkout_steps": [
        "tickets",
        "address",
        "form",
        "payment",
        "complete"
    ],
    "item_count": 3,
    "contact_id": 1390001,
    "guest_token": "af73d05bd847d66b62c21e56661c7069",
    "guest_checkout": true,
    "first_name": "Jeff",
    "last_name": "Blake",
    "email": "jeff@gmail.com",
    "phone_number": "+12068423456",
    "phone_number_country": "US",
    "completed_at": null,
    "expires_at": "2019-01-10T23:08:28.081445Z",
    "total": {
        "decimal": "40.08",
        "amount": 4008,
        "formatted": "$40.08"
    },
    "item_total": {
        "decimal": "45.0",
        "amount": 4500,
        "formatted": "$45.00"
    },
    "adjustment_total": {
        "decimal": "-4.92",
        "amount": -492,
        "formatted": "$-4.92"
    },
    "promo_total": {
        "decimal": "-9.0",
        "amount": -900,
        "formatted": "$-9.00"
    },
    "bill_address": null,
    "ship_address": null,
    "line_items": [
        {
            "id": 222988,
            "order_id": 214895,
            "name": "Sell tix",
            "description": null,
            "variant_id": 10542,
            "quantity": 3,
            "currency": "AUD",
            "bundle_item_id": null,
            "price": {
                "decimal": "15.0",
                "amount": 1500,
                "formatted": "$15.00"
            },
            "subtotal": {
                "decimal": "45.0",
                "amount": 4500,
                "formatted": "$45.00"
            }
        }
    ],
    "adjustments": [
        {
            "id": 405431,
            "label": "Promotion",
            "order_id": 214895,
            "adjustable_id": 222988,
            "adjustable_type": "LineItem",
            "source_id": 329,
            "source_type": "PromotionAction",
            "included": false,
            "mandatory": true,
            "eligible": true,
            "groupable": true,
            "finalized": false,
            "amount": {
                "decimal": "-9.0",
                "amount": -900,
                "formatted": "$-9.00"
            }
        },
        {
            "id": 405430,
            "label": "Service Fee",
            "order_id": 214895,
            "adjustable_id": 222988,
            "adjustable_type": "LineItem",
            "source_id": 4946,
            "source_type": "ServiceFeeRate",
            "included": false,
            "mandatory": true,
            "eligible": true,
            "groupable": true,
            "finalized": false,
            "amount": {
                "decimal": "4.08",
                "amount": 408,
                "formatted": "$4.08"
            }
        }
    ],
    "promotions": [
        {
            "id": 9185,
            "promotion_id": 301,
            "code": null
        }
    ],
    "tickets": [
        {
            "id": 2596880,
            "number": "sbAG83hpEeZNNXGxGChh8MCF",
            "status": "pending",
            "name": null,
            "email": null,
            "barcode": "6756402339979732",
            "note": null,
            "event_id": 71615,
            "ticket_type_id": 2470,
            "event_ticket_type_id": 19503,
            "list_id": 1017266,
            "contact_id": 1390001,
            "dispatched_at": null,
            "downloaded_at": null,
            "checkin_at": null,
            "source_type": "line_item",
            "source_id": 222988,
            "links": {
                "pdf": null,
                "wallet": null
            }
        },
        {
            "id": 2596879,
            "number": "DRHTvauq8N3Ay7ERFh7TUsmW",
            "status": "pending",
            "name": null,
            "email": null,
            "barcode": "2395309216989206",
            "note": null,
            "event_id": 71615,
            "ticket_type_id": 2470,
            "event_ticket_type_id": 19503,
            "list_id": 1017266,
            "contact_id": 1390001,
            "dispatched_at": null,
            "downloaded_at": null,
            "checkin_at": null,
            "source_type": "line_item",
            "source_id": 222988,
            "links": {
                "pdf": null,
                "wallet": null
            }
        },
        {
            "id": 2596878,
            "number": "nKUcCduXxmXN9DoYtsDnJqt4",
            "status": "pending",
            "name": null,
            "email": null,
            "barcode": "2208377212609034",
            "note": null,
            "event_id": 71615,
            "ticket_type_id": 2470,
            "event_ticket_type_id": 19503,
            "list_id": 1017266,
            "contact_id": 1390001,
            "dispatched_at": null,
            "downloaded_at": null,
            "checkin_at": null,
            "source_type": "line_item",
            "source_id": 222988,
            "links": {
                "pdf": null,
                "wallet": null
            }
        }
    ],
    "payments": [],
    "responses": [
        {
            "id": 52691,
            "form_id": 3587
        }
    ]
}

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.

This is a convenience endpoint as you do not need to submit the correct line_item_id parameter.

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

Remove item request

curl -X POST \
  https://app.guestmanager.com/api/public/v2/orders/214895/line_items/remove \
  -H 'Accept: application/json' \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "guest_token": "af73d05bd847d66b62c21e56661c7069",
    "variant_id": 10542,
    "quantity": 2
}'

Remove item response

{
    "id": 214895,
    "number": "GMIZAJD7EKOQUX",
    "currency": "AUD",
    "state": "cart",
    "checkout_steps": [
        "tickets",
        "address",
        "form",
        "payment",
        "complete"
    ],
    "item_count": 1,
    "contact_id": 1390001,
    "guest_token": "af73d05bd847d66b62c21e56661c7069",
    "guest_checkout": true,
    "first_name": "Jeff",
    "last_name": "Blake",
    "email": "jeff@gmail.com",
    "phone_number": "+12068423456",
    "phone_number_country": "US",
    "completed_at": null,
    "expires_at": "2019-01-10T23:08:28.081445Z",
    "total": {
        "decimal": "13.36",
        "amount": 1336,
        "formatted": "$13.36"
    },
    "item_total": {
        "decimal": "15.0",
        "amount": 1500,
        "formatted": "$15.00"
    },
    "adjustment_total": {
        "decimal": "-1.64",
        "amount": -164,
        "formatted": "$-1.64"
    },
    "promo_total": {
        "decimal": "-3.0",
        "amount": -300,
        "formatted": "$-3.00"
    },
    "bill_address": null,
    "ship_address": null,
    "line_items": [
        {
            "id": 222988,
            "order_id": 214895,
            "name": "Sell tix",
            "description": null,
            "variant_id": 10542,
            "quantity": 1,
            "currency": "AUD",
            "bundle_item_id": null,
            "price": {
                "decimal": "15.0",
                "amount": 1500,
                "formatted": "$15.00"
            },
            "subtotal": {
                "decimal": "15.0",
                "amount": 1500,
                "formatted": "$15.00"
            }
        }
    ],
    "adjustments": [
        {
            "id": 405431,
            "label": "Promotion",
            "order_id": 214895,
            "adjustable_id": 222988,
            "adjustable_type": "LineItem",
            "source_id": 329,
            "source_type": "PromotionAction",
            "included": false,
            "mandatory": true,
            "eligible": true,
            "groupable": true,
            "finalized": false,
            "amount": {
                "decimal": "-3.0",
                "amount": -300,
                "formatted": "$-3.00"
            }
        },
        {
            "id": 405430,
            "label": "Service Fee",
            "order_id": 214895,
            "adjustable_id": 222988,
            "adjustable_type": "LineItem",
            "source_id": 4946,
            "source_type": "ServiceFeeRate",
            "included": false,
            "mandatory": true,
            "eligible": true,
            "groupable": true,
            "finalized": false,
            "amount": {
                "decimal": "1.36",
                "amount": 136,
                "formatted": "$1.36"
            }
        }
    ],
    "promotions": [
        {
            "id": 9185,
            "promotion_id": 301,
            "code": null
        }
    ],
    "tickets": [
        {
            "id": 2596878,
            "number": "nKUcCduXxmXN9DoYtsDnJqt4",
            "status": "pending",
            "name": null,
            "email": null,
            "barcode": "2208377212609034",
            "note": null,
            "event_id": 71615,
            "ticket_type_id": 2470,
            "event_ticket_type_id": 19503,
            "list_id": 1017266,
            "contact_id": 1390001,
            "dispatched_at": null,
            "downloaded_at": null,
            "checkin_at": null,
            "source_type": "line_item",
            "source_id": 222988,
            "links": {
                "pdf": null,
                "wallet": null
            }
        }
    ],
    "payments": [],
    "responses": [
        {
            "id": 52691,
            "form_id": 3587
        }
    ]
}

Attempting to remove too many items (response)

{
    "type": "validation_error",
    "message": "Quantity Quantity must be greater than zero",
    "model": "LineItem",
    "id": 222988,
    "errors": {
        "attributes": [
            {
                "attribute": "quantity",
                "label": "Quantity",
                "code": "greater_than",
                "message": "Quantity must be greater than zero",
                "detail": {
                    "value": -3,
                    "count": -1
                }
            }
        ],
        "associations": {}
    }
}

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}

Delete line item request

curl -X DELETE \
  https://app.guestmanager.com/api/public/v2/orders/214895/line_items/222988 \
  -H 'Accept: application/json' \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "guest_token": "af73d05bd847d66b62c21e56661c7069"
}'

Delete line item response

{
    "id": 214895,
    "number": "GMIZAJD7EKOQUX",
    "currency": "AUD",
    "state": "cart",
    "checkout_steps": [
        "address",
        "complete"
    ],
    "item_count": 0,
    "contact_id": 1390001,
    "guest_token": "af73d05bd847d66b62c21e56661c7069",
    "guest_checkout": true,
    "first_name": "Jeff",
    "last_name": "Blake",
    "email": "jeff@gmail.com",
    "phone_number": "+12068423456",
    "phone_number_country": "US",
    "completed_at": null,
    "expires_at": "2019-01-10T23:08:28.081445Z",
    "total": {
        "decimal": "0.0",
        "amount": 0,
        "formatted": "$0.00"
    },
    "item_total": {
        "decimal": "0.0",
        "amount": 0,
        "formatted": "$0.00"
    },
    "adjustment_total": {
        "decimal": "0.0",
        "amount": 0,
        "formatted": "$0.00"
    },
    "promo_total": {
        "decimal": "0.0",
        "amount": 0,
        "formatted": "$0.00"
    },
    "bill_address": null,
    "ship_address": null,
    "line_items": [],
    "adjustments": [],
    "promotions": [
        {
            "id": 9185,
            "promotion_id": 301,
            "code": null
        }
    ],
    "tickets": [],
    "payments": [],
    "responses": [
        {
            "id": 52691,
            "form_id": 3587
        }
    ]
}

Parameters

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

Update line item

Updates a line item to a specified quantity.

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

Update line item request

curl -X PATCH \
  https://app.guestmanager.com/api/public/v2/orders/214895/line_items/222989 \
  -H 'Accept: application/json' \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "guest_token": "af73d05bd847d66b62c21e56661c7069",
    "line_item": {
        "quantity": 1
    }
}'

Update line item response

{
    "id": 214895,
    "number": "GMIZAJD7EKOQUX",
    "currency": "AUD",
    "state": "cart",
    "checkout_steps": [
        "tickets",
        "address",
        "form",
        "payment",
        "complete"
    ],
    "item_count": 1,
    "contact_id": 1390001,
    "guest_token": "af73d05bd847d66b62c21e56661c7069",
    "guest_checkout": true,
    "first_name": "Jeff",
    "last_name": "Blake",
    "email": "jeff@gmail.com",
    "phone_number": "+12068423456",
    "phone_number_country": "US",
    "completed_at": null,
    "expires_at": "2019-01-10T23:08:28.081445Z",
    "total": {
        "decimal": "16.45",
        "amount": 1645,
        "formatted": "$16.45"
    },
    "item_total": {
        "decimal": "15.0",
        "amount": 1500,
        "formatted": "$15.00"
    },
    "adjustment_total": {
        "decimal": "1.45",
        "amount": 145,
        "formatted": "$1.45"
    },
    "promo_total": {
        "decimal": "0.0",
        "amount": 0,
        "formatted": "$0.00"
    },
    "bill_address": null,
    "ship_address": null,
    "line_items": [
        {
            "id": 222989,
            "order_id": 214895,
            "name": "Sell tix",
            "description": null,
            "variant_id": 10542,
            "quantity": 1,
            "currency": "AUD",
            "bundle_item_id": null,
            "price": {
                "decimal": "15.0",
                "amount": 1500,
                "formatted": "$15.00"
            },
            "subtotal": {
                "decimal": "15.0",
                "amount": 1500,
                "formatted": "$15.00"
            }
        }
    ],
    "adjustments": [
        {
            "id": 405432,
            "label": "Service Fee",
            "order_id": 214895,
            "adjustable_id": 222989,
            "adjustable_type": "LineItem",
            "source_id": 4946,
            "source_type": "ServiceFeeRate",
            "included": false,
            "mandatory": true,
            "eligible": true,
            "groupable": true,
            "finalized": false,
            "amount": {
                "decimal": "1.45",
                "amount": 145,
                "formatted": "$1.45"
            }
        }
    ],
    "promotions": [
        {
            "id": 9185,
            "promotion_id": 301,
            "code": null
        }
    ],
    "tickets": [
        {
            "id": 2596882,
            "number": "cYV9WBPdCA71C2f6zw86GTK6",
            "status": "pending",
            "name": null,
            "email": null,
            "barcode": "2035349948646978",
            "note": null,
            "event_id": 71615,
            "ticket_type_id": 2470,
            "event_ticket_type_id": 19503,
            "list_id": 1017266,
            "contact_id": 1390001,
            "dispatched_at": null,
            "downloaded_at": null,
            "checkin_at": null,
            "source_type": "line_item",
            "source_id": 222989,
            "links": {
                "pdf": null,
                "wallet": null
            }
        },
        {
            "id": 2596881,
            "number": "gSH3Q7K1atT1EsEcVpUWTATr",
            "status": "pending",
            "name": null,
            "email": null,
            "barcode": "8393038480612290",
            "note": null,
            "event_id": 71615,
            "ticket_type_id": 2470,
            "event_ticket_type_id": 19503,
            "list_id": 1017266,
            "contact_id": 1390001,
            "dispatched_at": null,
            "downloaded_at": null,
            "checkin_at": null,
            "source_type": "line_item",
            "source_id": 222989,
            "links": {
                "pdf": null,
                "wallet": null
            }
        }
    ],
    "payments": [],
    "responses": [
        {
            "id": 52691,
            "form_id": 3587
        }
    ]
}

Request parameters

Parameter Type Description
{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.

It is highly recommended to thoroughly handle all possible errors, and to log any response code in the 4xx range for further review to ensure you are providing a good experience for your customers.

Checkout states

state Description
order_form Items in cart do not satisfy order form conditions.
email Standard checkout mode. You will not see this step in the API.
register Standard checkout mode. You will not see this step in the API.
tickets Any ticket types in the order are set to collect name and/or email.
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).
payment Order total is greater than 0.
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). Whenever you make an API call to update an order (add, remove items, transition checkout steps), if the order is expired, the system will attempt to automatically resume it before processing your request. Therefore, it is important that you are properly handling the response status code for every API call, as you could suddenly experience an error where the tickets are no longer available.

You can also manually resume an order if it is expired. This is the endpoint:

PATCH
/checkout/{id}/resume

Resume order

curl -X PATCH \
  https://app.guestmanager.com/api/public/v2/checkout/214895/resume \
  -H 'Accept: application/json' \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "guest_token": "af73d05bd847d66b62c21e56661c7069"
}'

Resume order successful

{
  "id": 214895,
  "state": "cart", // previous successful state
  ... omitted ...
}

Resume order error

{
    "type": "validation_error",
    "message": "State cannot transition via \"resume\"",
    "model": "Order",
    "id": 214895,
    "errors": {
        "attributes": [
            {
                "attribute": "state",
                "label": "State",
                "code": "invalid_transition",
                "message": "cannot transition via \"resume\"",
                "detail": {
                    "event": "resume",
                    "state": "cart"
                }
            }
        ],
        "associations": {
            "tickets": {},
            "form_responses": {},
            "line_items": {}
        }
    }
}

Request parameters

Parameter Description
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

Transition order to next state

curl -X PATCH \
  https://app.guestmanager.com/api/public/v2/checkout/214895/next \
  -H 'Accept: application/json' \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "guest_token": "af73d05bd847d66b62c21e56661c7069"
}'

Transition order success

{
    "id": 214895,
    "number": "GMIZAJD7EKOQUX",
    "currency": "AUD",
    "state": "tickets",
    "checkout_steps": [
        "tickets",
        "address",
        "form",
        "payment",
        "complete"
    ],
    "item_count": 1,
    "contact_id": 1390001,
    "guest_token": "af73d05bd847d66b62c21e56661c7069",
    "guest_checkout": true,
    "first_name": "Jeff",
    "last_name": "Blake",
    "email": "jeff@gmail.com",
    "phone_number": "+12068423456",
    "phone_number_country": "US",
    "completed_at": null,
    "expires_at": "2019-01-10T23:35:39.074446Z",
    "total": {
        "decimal": "16.45",
        "amount": 1645,
        "formatted": "$16.45"
    },
    "item_total": {
        "decimal": "15.0",
        "amount": 1500,
        "formatted": "$15.00"
    },
    "adjustment_total": {
        "decimal": "1.45",
        "amount": 145,
        "formatted": "$1.45"
    },
    "promo_total": {
        "decimal": "0.0",
        "amount": 0,
        "formatted": "$0.00"
    },
    "bill_address": null,
    "line_items": [
        {
            "id": 222989,
            "order_id": 214895,
            "name": "Sell tix",
            "description": null,
            "variant_id": 10542,
            "quantity": 1,
            "currency": "AUD",
            "bundle_item_id": null,
            "price": {
                "decimal": "15.0",
                "amount": 1500,
                "formatted": "$15.00"
            },
            "subtotal": {
                "decimal": "15.0",
                "amount": 1500,
                "formatted": "$15.00"
            }
        }
    ],
    "adjustments": [
        {
            "id": 405432,
            "label": "Service Fee",
            "order_id": 214895,
            "adjustable_id": 222989,
            "adjustable_type": "LineItem",
            "source_id": 4946,
            "source_type": "ServiceFeeRate",
            "included": false,
            "mandatory": true,
            "eligible": true,
            "groupable": true,
            "finalized": false,
            "amount": {
                "decimal": "1.45",
                "amount": 145,
                "formatted": "$1.45"
            }
        }
    ],
    "promotions": [
        {
            "id": 9185,
            "promotion_id": 301,
            "code": null
        }
    ],
    "tickets": [
        {
            "id": 2596882,
            "number": "cYV9WBPdCA71C2f6zw86GTK6",
            "status": "pending",
            "name": null,
            "email": null,
            "barcode": "2035349948646978",
            "note": null,
            "event_id": 71615,
            "ticket_type_id": 2470,
            "event_ticket_type_id": 19503,
            "list_id": 1017266,
            "contact_id": 1390001,
            "dispatched_at": null,
            "downloaded_at": null,
            "checkin_at": null,
            "source_type": "line_item",
            "source_id": 222989,
            "links": {
                "pdf": null,
                "wallet": null
            }
        },
        {
            "id": 2596881,
            "number": "gSH3Q7K1atT1EsEcVpUWTATr",
            "status": "pending",
            "name": null,
            "email": null,
            "barcode": "8393038480612290",
            "note": null,
            "event_id": 71615,
            "ticket_type_id": 2470,
            "event_ticket_type_id": 19503,
            "list_id": 1017266,
            "contact_id": 1390001,
            "dispatched_at": null,
            "downloaded_at": null,
            "checkin_at": null,
            "source_type": "line_item",
            "source_id": 222989,
            "links": {
                "pdf": null,
                "wallet": null
            }
        }
    ],
    "payments": [],
    "responses": [
        {
            "id": 52691,
            "form_id": 3587,
            "answers": [
                {
                    "id": 231811,
                    "form_field_id": 10773,
                    "value": null,
                    "human_value": null,
                    "field": {
                        "id": 10773,
                        "label": "Other",
                        "required": false,
                        "enabled": true,
                        "help_text": "",
                        "position": 3,
                        "type": "text_field",
                        "options": []
                    }
                },
                {
                    "id": 231810,
                    "form_field_id": 10646,
                    "value": null,
                    "human_value": null,
                    "field": {
                        "id": 10646,
                        "label": "Which Miele appliance do you own?",
                        "required": true,
                        "enabled": true,
                        "help_text": "",
                        "position": 2,
                        "type": "multiple_choice",
                        "options": [
                            {
                                "id": 498,
                                "form_field_id": 10646,
                                "name": "DGD 4635 Steam oven with pressure",
                                "value": "",
                                "type": null,
                                "position": 0
                            },
                            {
                                "id": 784,
                                "form_field_id": 10646,
                                "name": "Other (list below)",
                                "value": "",
                                "type": null,
                                "position": 99
                            }
                        ]
                    }
                },
                {
                    "id": 231809,
                    "form_field_id": 10647,
                    "value": null,
                    "human_value": null,
                    "field": {
                        "id": 10647,
                        "label": "When did you buy your appliance?",
                        "required": true,
                        "enabled": true,
                        "help_text": "",
                        "position": 1,
                        "type": "text_field",
                        "options": []
                    }
                },
                {
                    "id": 231808,
                    "form_field_id": 10658,
                    "value": null,
                    "human_value": null,
                    "field": {
                        "id": 10658,
                        "label": "How did you find out about the demonstration?",
                        "required": true,
                        "enabled": true,
                        "help_text": "",
                        "position": 0,
                        "type": "multiple_choice",
                        "options": [
                            {
                                "id": 893,
                                "form_field_id": 10658,
                                "name": "Referred by a Retailer",
                                "value": "",
                                "type": null,
                                "position": 0
                            },
                            {
                                "id": 783,
                                "form_field_id": 10658,
                                "name": "Friend Referral",
                                "value": "",
                                "type": null,
                                "position": 7
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

Request parameters

Parameter Description
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/{order-id}

See step for relevant example

curl -X PATCH \
  https://app.guestmanager.com/api/public/v2/checkout/214895/ \
  -H 'Accept: application/json' \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "guest_token": "af73d05bd847d66b62c21e56661c7069",
    "order": {
        "state": "tickets",
        ... step specific data ...
    }
}'

Request parameters

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

Parameter Required Description
guest_token yes Provide the order's guest_token to authorize updates to this order.
order[state] yes Provide the current state attribute that you are sending parameters for.
Step specific data. if required Include the relevant information specified below, according to the current step.

Response errors

invalid_state response 400 - Bad Request

{
    "type": "invalid_state",
    "message": "valid order states (tickets, address, form, payment, complete) does not include notastate",
    "error": true
}

Timer expired, items no longer available (sold_out)

{
    "type": "checkout_not_allowed",
    "message": "General Admission missing inventory.",
    "error": true,
    "detail": {
        "type": "validation_error",
        "message": "General Admission missing inventory.",
        "model": "Order",
        "id": 214895,
        "errors": {
            "attributes": [
                {
                    "attribute": "base",
                    "label": "Base",
                    "code": "invalid_inventory",
                    "message": "General Admission missing inventory.",
                    "detail": {}
                }
            ],
            "associations": {
                "tickets": {},
                "form_responses": {},
                "line_items": {}
            }
        }
    }
}

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 Response code Meaning
checkout_not_allowed 400 A variety of checks are performed to ensure an order may be checked out. See table below for definitions and sample error responses.
invalid_state 400 Order cannot transition to provided state, or the submitted state is not valid. Inspect checkout_steps

checkout_not_allowed explanations

Before we process your API call, we validate the order to ensure it is in a valid state. If it is not, you will receive response code 400 - Bad Request, with a json body containing a type attribute equal to checkout_not_allowed. The errors attribute will provide reasoning as to why.

The reasons are structured as validation_error objects under the errors key.

cart step

The default state of all newly created orders. cart is not a checkout_step.

tickets step

Checkout tickets step request

curl -X PATCH \
  https://app.guestmanager.com/api/public/v2/checkout/214896 \
  -H 'Accept: application/json' \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "guest_token": "5f0826c680f4eeb1d82522eda57c82c3",
    "order": {
        "state": "tickets",
        "tickets": [
            {
                "id": 2596884,
                "keep": true
            },
            {
                "id": 2596883,
                "name": "Bizzy Bone"
            }
        ]
    }
}'

Response 200

{
    "id": 214896,
    "number": "GMCDNR5AFLE3SG",
    "currency": "AUD",
    "state": "address",
    "checkout_steps": [
        "tickets",
        "address",
        "form",
        "payment",
        "complete"
    ],
    "item_count": 2,
    "contact_id": 1390001,
    "guest_token": "5f0826c680f4eeb1d82522eda57c82c3",
    "guest_checkout": true,
    "first_name": "Jeff",
    "last_name": "Blake",
    "email": "jeff@gmail.com",
    "phone_number": "+12068423456",
    "phone_number_country": "US",
    "completed_at": null,
    "expires_at": "2019-01-11T02:33:05.770844Z",
    "total": {
        "decimal": "32.9",
        "amount": 3290,
        "formatted": "$32.90"
    },
    "item_total": {
        "decimal": "30.0",
        "amount": 3000,
        "formatted": "$30.00"
    },
    "adjustment_total": {
        "decimal": "2.9",
        "amount": 290,
        "formatted": "$2.90"
    },
    "promo_total": {
        "decimal": "0.0",
        "amount": 0,
        "formatted": "$0.00"
    },
    "bill_address": null,
    "line_items": [
        {
            "id": 222990,
            "order_id": 214896,
            "name": "General Admission",
            "description": null,
            "variant_id": 10542,
            "quantity": 2,
            "currency": "AUD",
            "bundle_item_id": null,
            "price": {
                "decimal": "15.0",
                "amount": 1500,
                "formatted": "$15.00"
            },
            "subtotal": {
                "decimal": "30.0",
                "amount": 3000,
                "formatted": "$30.00"
            }
        }
    ],
    "adjustments": [
        {
            "id": 405433,
            "label": "Service Fee",
            "order_id": 214896,
            "adjustable_id": 222990,
            "adjustable_type": "LineItem",
            "source_id": 4946,
            "source_type": "ServiceFeeRate",
            "included": false,
            "mandatory": true,
            "eligible": true,
            "groupable": true,
            "finalized": false,
            "amount": {
                "decimal": "2.9",
                "amount": 290,
                "formatted": "$2.90"
            }
        }
    ],
    "promotions": [],
    "tickets": [
        {
            "id": 2596884,
            "number": "uFN3Ea5PzzjAGfcUWTgXxZrD",
            "status": "pending",
            "name": "Jeff Blake",
            "email": null,
            "barcode": "4315850278275881",
            "note": null,
            "event_id": 71615,
            "ticket_type_id": 2470,
            "event_ticket_type_id": 19503,
            "list_id": 1017266,
            "contact_id": 1390001,
            "dispatched_at": null,
            "downloaded_at": null,
            "checkin_at": null,
            "source_type": "line_item",
            "source_id": 222990,
            "links": {
                "pdf": null,
                "wallet": null
            }
        },
        {
            "id": 2596883,
            "number": "7TubHcKJU6fzL98ez6wPusLK",
            "status": "pending",
            "name": "Bizzy Bone",
            "email": null,
            "barcode": "4161426812156383",
            "note": null,
            "event_id": 71615,
            "ticket_type_id": 2470,
            "event_ticket_type_id": 19503,
            "list_id": 1017266,
            "contact_id": 1390001,
            "dispatched_at": null,
            "downloaded_at": null,
            "checkin_at": null,
            "source_type": "line_item",
            "source_id": 222990,
            "links": {
                "pdf": null,
                "wallet": null
            }
        }
    ],
    "payments": [],
    "responses": [
        {
            "id": 52692,
            "form_id": 3587,
            "answers": [
                {
                    "id": 231815,
                    "form_field_id": 10773,
                    "value": null,
                    "human_value": null,
                    "field": {
                        "id": 10773,
                        "label": "Other",
                        "required": false,
                        "enabled": true,
                        "help_text": "",
                        "position": 3,
                        "type": "text_field",
                        "options": []
                    }
                },
                {
                    "id": 231814,
                    "form_field_id": 10646,
                    "value": null,
                    "human_value": null,
                    "field": {
                        "id": 10646,
                        "label": "Which Miele appliance do you own?",
                        "required": true,
                        "enabled": true,
                        "help_text": "",
                        "position": 2,
                        "type": "multiple_choice",
                        "options": [
                            {
                                "id": 498,
                                "form_field_id": 10646,
                                "name": "DGD 4635 Steam oven with pressure",
                                "value": "",
                                "type": null,
                                "position": 0
                            }
                        ]
                    }
                },
                {
                    "id": 231813,
                    "form_field_id": 10647,
                    "value": null,
                    "human_value": null,
                    "field": {
                        "id": 10647,
                        "label": "When did you buy your appliance?",
                        "required": true,
                        "enabled": true,
                        "help_text": "",
                        "position": 1,
                        "type": "text_field",
                        "options": []
                    }
                },
                {
                    "id": 231812,
                    "form_field_id": 10658,
                    "value": null,
                    "human_value": null,
                    "field": {
                        "id": 10658,
                        "label": "How did you find out about the demonstration?",
                        "required": true,
                        "enabled": true,
                        "help_text": "",
                        "position": 0,
                        "type": "multiple_choice",
                        "options": [
                            {
                                "id": 783,
                                "form_field_id": 10658,
                                "name": "Friend Referral",
                                "value": "",
                                "type": null,
                                "position": 7
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

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 array on the order will dictate which tickets need to be updated with names and/or emails. You must provide the id of each ticket in the array.

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

422 - Unprocessable Entity response

{
    "type": "validation_error",
    "message": "Cannot transition state via :next from :tickets (Reason(s): Transition halted)",
    "model": "Order",
    "id": 214896,
    "errors": {
        "attributes": [],
        "associations": {
            "tickets": {
                "2596883": {
                    "type": "validation_error",
                    "message": "Name can't be blank",
                    "model": "Ticket",
                    "id": 2596883,
                    "errors": {
                        "attributes": [
                            {
                                "attribute": "name",
                                "label": "Name",
                                "name": null,
                                "code": "blank",
                                "message": "can't be blank",
                                "detail": {}
                            }
                        ],
                        "associations": {}
                    }
                }
            },
            "form_responses": {},
            "line_items": {}
        }
    }
}

Request parameters

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

Notes

address step

Checkout address step request

curl -X PATCH \
  https://app.guestmanager.com/api/public/v2/checkout/214896 \
  -H 'Accept: application/json' \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "guest_token": "5f0826c680f4eeb1d82522eda57c82c3",
    "order": {
        "state": "address",
        "bill_address": {
            "address1": "123 Main Street",
            "city": "Anytown",
            "zipcode": "92109",
            "state_code": "WA",
            "country_code": "US"
        }
    }
}'

200 response

{
    "id": 214896,
    "number": "GMCDNR5AFLE3SG",
    "currency": "AUD",
    "state": "form",
    "checkout_steps": [
        "tickets",
        "address",
        "form",
        "payment",
        "complete"
    ],
    "item_count": 2,
    "contact_id": 1390001,
    "guest_token": "5f0826c680f4eeb1d82522eda57c82c3",
    "guest_checkout": true,
    "first_name": "Jeff",
    "last_name": "Blake",
    "email": "jeff@gmail.com",
    "phone_number": "+12068423456",
    "phone_number_country": "US",
    "completed_at": null,
    "expires_at": "2019-01-11T02:33:05.770844Z",
    "total": {
        "decimal": "32.9",
        "amount": 3290,
        "formatted": "$32.90"
    },
    "item_total": {
        "decimal": "30.0",
        "amount": 3000,
        "formatted": "$30.00"
    },
    "adjustment_total": {
        "decimal": "2.9",
        "amount": 290,
        "formatted": "$2.90"
    },
    "promo_total": {
        "decimal": "0.0",
        "amount": 0,
        "formatted": "$0.00"
    },
    "bill_address": {
        "id": 144812,
        "address1": "123 Main Street",
        "city": "Anytown",
        "zipcode": "92109",
        "state_name": "Washington",
        "state_code": "WA",
        "country_name": "United States",
        "country_code": "US"
    },
    "line_items": [
        {
            "id": 222990,
            "order_id": 214896,
            "name": "General Admission",
            "description": null,
            "variant_id": 10542,
            "quantity": 2,
            "currency": "AUD",
            "bundle_item_id": null,
            "price": {
                "decimal": "15.0",
                "amount": 1500,
                "formatted": "$15.00"
            },
            "subtotal": {
                "decimal": "30.0",
                "amount": 3000,
                "formatted": "$30.00"
            }
        }
    ],
    "adjustments": [
        {
            "id": 405433,
            "label": "Service Fee",
            "order_id": 214896,
            "adjustable_id": 222990,
            "adjustable_type": "LineItem",
            "source_id": 4946,
            "source_type": "ServiceFeeRate",
            "included": false,
            "mandatory": true,
            "eligible": true,
            "groupable": true,
            "finalized": false,
            "amount": {
                "decimal": "2.9",
                "amount": 290,
                "formatted": "$2.90"
            }
        }
    ],
    "promotions": [],
    "tickets": [
        {
            "id": 2596883,
            "number": "7TubHcKJU6fzL98ez6wPusLK",
            "status": "pending",
            "name": "Bizzy Bone",
            "email": null,
            "barcode": "4161426812156383",
            "note": null,
            "event_id": 71615,
            "ticket_type_id": 2470,
            "event_ticket_type_id": 19503,
            "list_id": 1017266,
            "contact_id": 1390001,
            "dispatched_at": null,
            "downloaded_at": null,
            "checkin_at": null,
            "source_type": "line_item",
            "source_id": 222990,
            "links": {
                "pdf": null,
                "wallet": null
            }
        },
        {
            "id": 2596884,
            "number": "uFN3Ea5PzzjAGfcUWTgXxZrD",
            "status": "pending",
            "name": "Jeff Blake",
            "email": null,
            "barcode": "4315850278275881",
            "note": null,
            "event_id": 71615,
            "ticket_type_id": 2470,
            "event_ticket_type_id": 19503,
            "list_id": 1017266,
            "contact_id": 1390001,
            "dispatched_at": null,
            "downloaded_at": null,
            "checkin_at": null,
            "source_type": "line_item",
            "source_id": 222990,
            "links": {
                "pdf": null,
                "wallet": null
            }
        }
    ],
    "payments": [],
    "responses": [
        {
            "id": 52692,
            "form_id": 3587,
            "answers": [
                {
                    "id": 231815,
                    "form_field_id": 10773,
                    "value": null,
                    "human_value": null,
                    "field": {
                        "id": 10773,
                        "label": "Other",
                        "required": false,
                        "enabled": true,
                        "help_text": "",
                        "position": 3,
                        "type": "text_field",
                        "options": []
                    }
                },
                {
                    "id": 231814,
                    "form_field_id": 10646,
                    "value": null,
                    "human_value": null,
                    "field": {
                        "id": 10646,
                        "label": "Which Miele appliance do you own?",
                        "required": true,
                        "enabled": true,
                        "help_text": "",
                        "position": 2,
                        "type": "multiple_choice",
                        "options": [
                            {
                                "id": 498,
                                "form_field_id": 10646,
                                "name": "DGD 4635 Steam oven with pressure",
                                "value": "",
                                "type": null,
                                "position": 0
                            }
                        ]
                    }
                },
                {
                    "id": 231813,
                    "form_field_id": 10647,
                    "value": null,
                    "human_value": null,
                    "field": {
                        "id": 10647,
                        "label": "When did you buy your appliance?",
                        "required": true,
                        "enabled": true,
                        "help_text": "",
                        "position": 1,
                        "type": "text_field",
                        "options": []
                    }
                },
                {
                    "id": 231812,
                    "form_field_id": 10658,
                    "value": null,
                    "human_value": null,
                    "field": {
                        "id": 10658,
                        "label": "How did you find out about the demonstration?",
                        "required": true,
                        "enabled": true,
                        "help_text": "",
                        "position": 0,
                        "type": "multiple_choice",
                        "options": [
                            {
                                "id": 893,
                                "form_field_id": 10658,
                                "name": "Referred by a Retailer",
                                "value": "",
                                "type": null,
                                "position": 0
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

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.

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 Required Description
order[bill_address] object yes See Address for format.
order[ship_address] object *if delivery step present See Address for format.

Response

Upon successful addition of address information, you will see a populated bill_address_id and/or ship_address_id, and corresponding bill_address and ship_address relationships on the order.

form step

Checkout form step request

curl -X PATCH \
  https://app.guestmanager.com/api/public/v2/checkout/214896 \
  -H 'Accept: application/json' \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "guest_token": "5f0826c680f4eeb1d82522eda57c82c3",
    "order": {
        "state": "form",
        "responses": [
            {
                "id": 52692,
                "answers": [
                    {
                        "id": 231815,
                        "value": "text field answer"
                    },
                    {
                        "id": 231814,
                        "value": 784 /* multiple choice `field_id` */
                    },
                    {
                        "id": 231813,
                        "value": "January"
                    },
                    {
                        "id": 231812,
                        "value": 580 /* multiple choice `field_id` */
                    }
                ]
            }
        ]
    }
}'

200 response

{
    "id": 214896,
    "number": "GMCDNR5AFLE3SG",
    "currency": "AUD",
    "state": "payment",
    "checkout_steps": [
        "tickets",
        "address",
        "form",
        "payment",
        "complete"
    ],
    "item_count": 2,
    "contact_id": 1390001,
    "guest_token": "5f0826c680f4eeb1d82522eda57c82c3",
    "guest_checkout": true,
    "first_name": "Jeff",
    "last_name": "Blake",
    "email": "jeff@gmail.com",
    "phone_number": "+12068423456",
    "phone_number_country": "US",
    "completed_at": null,
    "expires_at": "2019-01-11T02:49:39.185424Z",
    "total": {
        "decimal": "32.9",
        "amount": 3290,
        "formatted": "$32.90"
    },
    "item_total": {
        "decimal": "30.0",
        "amount": 3000,
        "formatted": "$30.00"
    },
    "adjustment_total": {
        "decimal": "2.9",
        "amount": 290,
        "formatted": "$2.90"
    },
    "promo_total": {
        "decimal": "0.0",
        "amount": 0,
        "formatted": "$0.00"
    },
    "bill_address": {
        "id": 144813,
        "address1": "123 Main Street",
        "city": "Anytown",
        "zipcode": "92109",
        "state_name": null,
        "state_code": null,
        "country_name": "United States",
        "country_code": "US"
    },
    "line_items": [
        {
            "id": 222990,
            "order_id": 214896,
            "name": "General Admission",
            "description": null,
            "variant_id": 10542,
            "quantity": 2,
            "currency": "AUD",
            "bundle_item_id": null,
            "price": {
                "decimal": "15.0",
                "amount": 1500,
                "formatted": "$15.00"
            },
            "subtotal": {
                "decimal": "30.0",
                "amount": 3000,
                "formatted": "$30.00"
            }
        }
    ],
    "adjustments": [
        {
            "id": 405433,
            "label": "Service Fee",
            "order_id": 214896,
            "adjustable_id": 222990,
            "adjustable_type": "LineItem",
            "source_id": 4946,
            "source_type": "ServiceFeeRate",
            "included": false,
            "mandatory": true,
            "eligible": true,
            "groupable": true,
            "finalized": false,
            "amount": {
                "decimal": "2.9",
                "amount": 290,
                "formatted": "$2.90"
            }
        }
    ],
    "promotions": [],
    "tickets": [
        {
            "id": 2596883,
            "number": "7TubHcKJU6fzL98ez6wPusLK",
            "status": "pending",
            "name": "Bizzy Bone",
            "email": null,
            "barcode": "4161426812156383",
            "note": null,
            "event_id": 71615,
            "ticket_type_id": 2470,
            "event_ticket_type_id": 19503,
            "list_id": 1017266,
            "contact_id": 1390001,
            "dispatched_at": null,
            "downloaded_at": null,
            "checkin_at": null,
            "source_type": "line_item",
            "source_id": 222990,
            "links": {
                "pdf": null,
                "wallet": null
            }
        },
        {
            "id": 2596884,
            "number": "uFN3Ea5PzzjAGfcUWTgXxZrD",
            "status": "pending",
            "name": "Jeff Blake",
            "email": null,
            "barcode": "4315850278275881",
            "note": null,
            "event_id": 71615,
            "ticket_type_id": 2470,
            "event_ticket_type_id": 19503,
            "list_id": 1017266,
            "contact_id": 1390001,
            "dispatched_at": null,
            "downloaded_at": null,
            "checkin_at": null,
            "source_type": "line_item",
            "source_id": 222990,
            "links": {
                "pdf": null,
                "wallet": null
            }
        }
    ],
    "payments": [],
    "responses": [
        {
            "id": 52692,
            "form_id": 3587,
            "answers": [
                {
                    "id": 231815,
                    "form_field_id": 10773,
                    "value": "text field answer",
                    "human_value": "text field answer",
                    "field": {
                        "id": 10773,
                        "label": "Other",
                        "required": false,
                        "enabled": true,
                        "help_text": "",
                        "position": 3,
                        "type": "text_field",
                        "options": []
                    }
                },
                {
                    "id": 231814,
                    "form_field_id": 10646,
                    "value": "784",
                    "human_value": "Other (list below)",
                    "field": {
                        "id": 10646,
                        "label": "Which Miele appliance do you own?",
                        "required": true,
                        "enabled": true,
                        "help_text": "",
                        "position": 2,
                        "type": "multiple_choice",
                        "options": [
                            {
                                "id": 498,
                                "form_field_id": 10646,
                                "name": "DGD 4635 Steam oven with pressure",
                                "value": "",
                                "type": null,
                                "position": 0
                            }
                        ]
                    }
                },
                {
                    "id": 231813,
                    "form_field_id": 10647,
                    "value": "January",
                    "human_value": "January",
                    "field": {
                        "id": 10647,
                        "label": "When did you buy your appliance?",
                        "required": true,
                        "enabled": true,
                        "help_text": "",
                        "position": 1,
                        "type": "text_field",
                        "options": []
                    }
                },
                {
                    "id": 231812,
                    "form_field_id": 10658,
                    "value": "580",
                    "human_value": "Miele Experience Website",
                    "field": {
                        "id": 10658,
                        "label": "How did you find out about the demonstration?",
                        "required": true,
                        "enabled": true,
                        "help_text": "",
                        "position": 0,
                        "type": "multiple_choice",
                        "options": [
                            {
                                "id": 893,
                                "form_field_id": 10658,
                                "name": "Referred by a Retailer",
                                "value": "",
                                "type": null,
                                "position": 0
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

Example Response (Error)

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

Parameter Type Description
order[responses] array See Response object 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

See Objects section for details on the fields and relationships.

List tickets

Request

GET
/tickets

List tickets for specific event

curl -X GET \
  https://app.guestmanager.com/api/public/v2/tickets \
  -H 'Authorization: Token abcedfg' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
        "event_ids": "1234"
    }
  }'

Parameters

Parameter Type Required Default Description
page[size] integer no 10 How many records to return per request. Default is 10, maximum is 50
page[number] integer no 1 The page of records to request.
sort[{field}] string no none Replace {field} with one of id, created_at, updated_at, and set the value to asc or desc. You may specify multiple sort fields.
fields string no id,name Comma separated list of attributes to return.
include string no none Relationships to include.
filter[event_ids] string no none Filter by event. Comma separated string of event IDs.
filter[list_ids] string no none Filter by event lists. Comma separated string of IDs.

Fetch ticket

Request

GET
/tickets/{id}

Fetch ticket

curl -X GET \
  https://app.guestmanager.com/api/public/v2/tickets/2307131 \
  -H 'Authorization: Token abcedfg' \
  -H 'Content-Type: application/json' \

Parameters

No parameters.

Create ticket

Request

POST
/tickets

Request (Barebones ticket)

curl -X POST \
  https://app.guestmanager.com/api/public/v2/tickets \
  -H 'Authorization: Token abbcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "ticket": {
        "event_ticket_type_id": 19054
    }
}'

Response (Barebones ticket)

{
    "id": 2589825,
    "number": "eqRNGyHe9eygZJy4nYpHf6Qx",
    "status": "valid",
    "name": null,
    "email": null,
    "barcode": "0574501952988944",
    "note": null,
    "event_id": 71389,
    "ticket_type_id": 3937,
    "event_ticket_type_id": 19054,
    "list_id": 1016743,
    "source_id": null,
    "source_type": null,
    "contact_id": null,
    "dispatched_at": null,
    "downloaded_at": null,
    "checkin_at": null,
    "guest": null,
    "links": {
        "pdf": "https://client.guestmanager.com/tickets/pMWFB5yZ6yasd3idtoJE7pfCfc.pdf",
        "wallet": null
    }
}

Create and email ticket

curl -X POST \
  https://app.guestmanager.com/api/public/v2/tickets \
  -H 'Authorization: Token abcedg' \
  -H 'Content-Type: application/json' \
  -d '{
    "ticket": {
        "event_ticket_type_id": 19054,
        "name": "Jeff Blake",
        "email": "jeff@guestmanager.com",
        "dispatch": true
    }
}'
# Inspect response carefully: An invalid email or un-configured Ticket design will trigger error `422`
# `dispatched_at` will return null, but will be updated asynchronously upon successful email delivery

Create ticket assigned to contact

# This method is preferred over specifying a ticket name and email, as it associates the ticket to an existing contact record.
curl -X POST \
  https://app.guestmanager.com/api/public/v2/tickets \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "ticket": {
        "event_ticket_type_id": 19054,
        "contact_id": 1384595
    }
}'

Response

{
    "id": 2589827,
    "number": "JQ2WDaYZwzgXXZ9MDr3uSm7E",
    "status": "valid",
    "name": null,
    "email": null,
    "barcode": "8710305528892125",
    "note": null,
    "event_id": 71389,
    "ticket_type_id": 3937,
    "event_ticket_type_id": 19054,
    "list_id": 1016743,
    "source_id": null,
    "source_type": null,
    "contact_id": 1384595,
    "dispatched_at": null,
    "downloaded_at": null,
    "checkin_at": null,
    "contact": {
        "id": 1384595,
        "identifier": null,
        "name": "Mandy Jones",
        "first_name": "Mandy",
        "last_name": "Jones",
        "email": "****@hotmail.com"
    },
    "links": {
        "pdf": "https://client.guestmanager.com/tickets/pMWFB5yZas3fdtoJE7pfCfc.pdf",
        "wallet": null
    }
}

Create ticket with custom fields (specifying field_id)

curl -X POST \
  https://app.guestmanager.com/api/public/v2/tickets \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "ticket": {
        "event_ticket_type_id": 19054,
        "contact_id": 1384595,
        "custom_fields": [
          {
            "field_id": 12345,
            "value": "a custom field"
          }
        ]
    }
}'

Create ticket with custom fields (specifying label)

curl -X POST \
  https://app.guestmanager.com/api/public/v2/tickets \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "ticket": {
        "event_ticket_type_id": 19054,
        "contact_id": 1384595,
        "custom_fields": [
          {
            "label": "Title",
            "value": "CEO"
          },
          {
            "label": "Company",
            "value": "ACME Inc."
          }
        ]
    }
}'

Parameters

Parameter Type Required Description
ticket[name] string No Name to be shown on the ticket. Automatically set if contact_id is provided.
ticket[email] string No Email address of the ticket owner. Automatically set if contact_id is provided.
ticket[contact_id] int No Link a guest in your database as the owner of this ticket.
ticket[event_ticket_type_id] int No, if both event_id and ticket_type_id are provided. The Ticket Type to assign to the ticket.
ticket[ticket_type_id] int No, if event_ticket_type_id is provided. The ticket type to assign this ticket to.
ticket[event_id] int No, if event_ticket_type_id is provided. The event to assign this ticket to.
ticket[dispatch] boolean No If true, an email is dispatched to the owner of the ticket, with the ticket as a PDF attachment.
ticket[barcode] string No A barcode number will be automatically generated if one is not provided.
ticket[list_id] int No The list to assign this ticket to. If not provided, defaults to the company master list.
ticket[permanent_list_id] int No The permanent list. If provided, the event specific list_id will be automatically set.
ticket[custom_fields] array No User defined custom fields. For each object, provide value and either field_id or label. See example.

Update ticket

Request

PATCH
/tickets/{id}

Update ticket

curl -X PATCH \
  https://app.guestmanager.com/api/public/v2/tickets/2589827 \
  -H 'Authorization: Token abcedfg' \
  -H 'Content-Type: application/json' \
  -d '{
    "ticket": {
        "name": "new name",
        "email": "newemail@gmail.com"
    }
}'

Response

{
    "id": 2589827,
    "number": "JQ2WDaYZwzgXXZ9MDr3uSm7E",
    "status": "valid",
    "name": "New name",
    "email": "newemail@gmail.com",
    "barcode": "8710305528892125",
    "note": null,
    "event_id": 71389,
    "ticket_type_id": 3937,
    "event_ticket_type_id": 19054,
    "list_id": 1016743,
    "source_type": null,
    "source_id": null,
    "contact_id": 1384595,
    "dispatched_at": null,
    "downloaded_at": null,
    "checkin_at": null,
    "contact": {
        "id": 1384595,
        "identifier": null,
        "name": "Mandy Jones",
        "first_name": "Mandy",
        "last_name": "Jones",
        "email": "****@hotmail.com"
    },
    "links": {
        "pdf": "https://miele.guestmanager.com/tickets/pMWFB5a3tdNidtoJE7pfCfc.pdf",
        "wallet": null
    }
}

Parameters

See parameters for create a ticket.

Delete ticket

DELETE
/tickets/{id}

Request

curl -X DELETE \
  https://app.guestmanager.com/api/public/v2/tickets/2589827 \
  -H 'Authorization: Token abcedfg' \
  -H 'Content-Type: application/json' \

Response

Successfully deleting a ticket will return response code 204 - No Content with an empty response body.

Email ticket

Send an email to the ticket holder containing their ticket (either attached as a PDF, or as a downloadable link, depending on your configuration).

PATCH
/tickets/{id}/email

Response

Response code Successful? Description
200 Yes
422 No Common issues: Ticket does not have an email address, or the ticket design has not been configured on the event or ticket type.

Email ticket

curl -X PATCH \
  https://app.guestmanager.com/api/public/v2/tickets/2589827/email \
  -H 'Authorization: Token abcedfg' \
  -H 'Content-Type: application/json' \

Email multiple tickets

Send multiple tickets in a single email.

PATCH
/tickets/bulk_email

Email multiple tickets

curl -X PATCH \
  https://app.guestmanager.com/api/public/v2/tickets/bulk_email \
  -H 'Accept: */*' \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "ids": "2368510,2607936",
    "email": "jeff@test.com",
  "subject": "Custom subject line"
}'

Sample response

{
    "id": 1223527,
    "created_at": "2019-07-16T00:13:14.313530Z",
    "updated_at": "2019-07-16T00:13:14.313530Z",
    "type": "ticket_multiple_email",
    "email": "jeff@test.com",
    "state": "draft",
    "status": "unopened",
    "delivery_error_detail": null,
    "click_count": 0,
    "open_count": 0,
    "subject": "My custom subject",
    "body": null
}

Request parameters

Parameter Type Required Description
ids array, or comma separated string yes The ID numbers of the tickets to include in the email.
email string yes The email address to send the tickets to.
subject string no Optional custom subject line.
body string no Optional custom email body. HTML is supported.
email_template_id integer no Use a custom pre-created email template (optional).

Response

Response code Successful? Description
200 Yes Email is queued for delivery. an Email record is returned in the API call.
422 No Invalid ticket ID's, or email address.

Void ticket

Voiding a ticket will change the status to invalidated and send an email to the ticket holder notifying them that their ticket is no longer valid.

PATCH
/tickets/{id}/void

Void ticket

curl -X PATCH \
  https://app.guestmanager.com/api/public/v2/tickets/2589827/void \
  -H 'Authorization: Token abcedfg' \
  -H 'Content-Type: application/json' \

Countries

See Objects section for details on the fields and relationships.

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

This endpoint is not paginated.

List countries

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

Response

[
    {
        "id": 3,
        "name": "Afghanistan",
        "code": "AF",
        "phone_prefix": "93",
        "currency_code": "AFN"
    },
    {
        "id": 6,
        "name": "Albania",
        "code": "AL",
        "phone_prefix": "355",
        "currency_code": "ALL"
    },
    ...
]

List country states

See Objects section for details on the fields and relationships.

GET
/countries/{country-id}/states

This endpoint is not paginated.

List states (for USA)

curl -X GET \
  https://app.guestmanager.com/api/public/v2/countries/234/states \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \

Response

[
    {
        "id": 4122,
        "name": "Alabama",
        "country_id": 234,
        "code": "AL"
    },
    {
        "id": 4121,
        "name": "Alaska",
        "country_id": 234,
        "code": "AK"
    },
    ...
]

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

Authentication is done through an Authorization header. Please see the example on the right. A successful request (for testing purposes) will respond with your enterprise name and ID. All API requests are stateless, so include this Authorization header in all requests, or you will receive a response code 401 with body HTTP Token: Access denied.

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.

Company object

{
    "id": 4412,
    "name": "Company ABC",
    "password": "****",
    "pin": 5988,
    "created_at": "2018-12-07T12:52:54.665871Z",
    "updated_at": "2018-12-07T12:52:55.939928Z",
    "api_keys": [
        {
            "id": 0,
            "name": null,
            "access_token": "....",
            "read": true,
            "write": true
        },
        {
            "id": 0,
            "name": null,
            "access_token": "....",
            "read": true,
            "write": false
        }
    ],
    "users": [
        {
            "id": 9175,
            "name": "John Doe",
            "email": "john@doe.com"
        }
    ],
    "address": {
        "id": 0,
        "address1": null,
        "city": null,
        "zipcode": null,
        "state_name": null,
        "state_code": null,
        "country_name": "United States",
        "country_code": "US"
    }
}

Companies are your clients. Every company is a separate silo of data: events, contacts, tickets, etc.

Company fields

Attribute Type Description
id int ID of the company. Can, for example, be used to query the events endpoint using the company_id parameter.
name string Name of the company.
password string The password used to log into the Check In App.
pin string The default PIN number to log into the Check In App with.

Company relationships

Key Relationship Type
address Address object
api_keys ApiKey array
users CompanyUser array

List companies

GET
/companies

Request

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

Response

{
    "data": [
        {
            "id": 4412,
            "name": "Company a"
        },
        {
            "id": 4413,
            "name": "Company b"
        }
    ],
    "meta": {
        "count": 2,
        "total": 2,
        "page": {
            "number": 1,
            "size": 10,
            "next": null,
            "prev": null,
            "total": 1,
            "last": true,
            "first": true,
            "out_of_range": false
        },
        "links": {
            "self": ".../api/public/enterprise/v1/companies",
            "next": null,
            "prev": null,
            "last": ".../api/public/enterprise/v1/companies?page%5Bnumber%5D=1",
            "first": ".../api/public/enterprise/v1/companies?page%5Bnumber%5D=1"
        }
    }
}

Request parameters

Parameter Type Required Default Description
page[size] integer no 10 How many records to return per request. Default is 10, maximum is 100
page[number] integer no 1 The page of records to request.
sort[{field}] string no none The field to sort results by. Can be id, name, with value asc or desc
fields string no id,name Comma separated list of attributes to return. See company object for possible fields.
include string no Relationships to include. See company object for possible relationships.

Response data

An array of company objects will be returned in the data key. Pagination information is in the meta key.

Create company

POST
/companies

Request parameters

Parameter Type Required Description
company[name] string yes Company name.
company[address][country_code] string yes ISO code of the company's country.

Sample request

curl -X POST \
  https://app.guestmanager.com/api/public/enterprise/v1/companies \
  -H 'Authorization: Token abcdefg' \
  -H 'Content-Type: application/json' \
  -d '{
    "company": {
        "name": "New company",
        "address": {
            "country_code": "US"
        }
    }
}'

Response

You will receive back two API keys, one authorized for read only, and the other authorized for read and writes. Please store the Company id, and api_keys in your own database, as you will need these to perform API requests on behalf of your clients.

The password and pin are used to log in to the iOS Check In App.

Sample response

{
  "id": 10,
  "name": "New company",
  "password": "******",
  "pin": "1234",
  "address": {
    "country_code": "US"
  },
  "api_keys": [
    {
      "id": 1234,
      "name": null,
      "access_token": "....",
      "read": true,
      "write": false
    },
    {
      "id": 1235,
      "name": null,
      "access_token": "....",
      "read": true,
      "write": true
    }
  ]
}

List events

See Objects section for details on the fields and relationships.

GET
/events

Request parameters

Sample request

curl -X GET \
  https://app.guestmanager.com/api/public/enterprise/v1/events \
  -H 'Authorization: Token abcedf' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
        "company_id": 123
    },
    "sort": {
        "starts_at": "asc"
    },
    "page": {
        "size": 10,
        "number": 2
    },
    "include": "registration_types.prices"
}'

Sample response

Please refer to the List events endpoint for a complete list of request parameters. In addition to those, the following are exclusive to the enterprise endpoint:

Parameter Type Required Default Description
filter[company_id] integer no none Filter by company.

Objects

Common fields

Field Type Description
id int Unique identifier. read-only
created_at datetime When this object was created. read-only
updated_at datetime When this object was last updated. read-only

Data types

money data type

{
    "decimal": "53.5",
    "amount": 5350, // Integer
    "formatted": "$53.50" // Includes appropriate currency symbol
}
Type Example Description
date 2018-05-25 yyyy-mm-dd
datetime "2017-10-25T17:54:51.557604Z" iso8601 format in the UTC time zone.
decimal 102.56 Decimals are provided as a string.
image { "original": "...com/image.jpg" } Images are put into an object. Additional keys can be added dynamically for altering images. Refer to Topics on how to achieve this.
money { "decimal": "10.0", "amount": 1000, "formatted": "$10.00" } A money attribute is an object that includes a few different representations of the amount, mostly for convenience.

Email

Email object

  {
      "id": 894675,
      "created_at": "2018-06-04T16:48:50.245304Z",
      "updated_at": "2018-06-04T17:04:26.582437Z",
      "type": "ticket_email",
      "email": "*****@gmail.com",
      "state": "delivered",
      "status": "opened",
      "delivery_error_detail": null,
      "click_count": 0,
      "open_count": 3,
      "subject": "Your Ticket attached!",
      "body": null
  }
Field Type Description
email string Email address this email was sent to. read-only
type string The type of email that was sent. read-only
state string Delivery status. See below for descriptions. read-only
status string How the recipient responded to the email. See below for descriptions. read-only
delivery_error_detail string If the state is not delivered, you may inspect this field to see why. read-only
open_count int How many times the email was opened. read-only
click_count int How many times a link was clicked in the email. read-only
subject string The email subject. read-only
body string The HTML body of the email. This field will be null after approximately 6 months. read-only

Email type

Type Description
ticket_email Ticket was sent to the guest, either as a PDF attachment or a downloadable link, depending on your configuration.

Email state

State Successful? Description
draft No Email has been queued for delivery.
delivering No Email is currently being sent.
delivered Yes Email was sent successfully.
bounced No Bounce. See delivery_error_detail for more information.
dropped No Email was canceled due to previously known issue with this email address.
canceled No Email was canceled due to condition that made this email no longer relevant. e.g. the ticket was deleted.

Email status

State Description
unopened Email has not been opened yet.
opened Email was opened.
clicked Recipient clicked a link in the email.
spammed Recipient reported this email as spam.
unsubscribed Recipient unsubscribed.

Event

Event object

{
    "id": 59978,
    "name": "Gourmet Steam Oven",
    "slug": "gourmet-steam-oven-10-30am-12-00pm",
    "status": "past",
    "venue_id": 1989,
    "parent_event_id": 59918,
    "calendar_id": 7,
    "published_at": "2016-10-17T01:08:42.038414Z",
    "start": {
        "tz": "Melbourne",
        "local": "2016-10-28T10:30:00+11:00",
        "utc": "2016-10-27T23:30:00Z"
    },
    "end": {
        "tz": "Melbourne",
        "local": "2016-10-28T12:00:00+11:00",
        "utc": "2016-10-28T01:00:00Z"
    },
    "venue": {
        "id": 1989,
        "name": "South Melbourne",
        "description": null,
        "slug": "south-melbourne"
    },
    "tags": [
        {
            "id": 297,
            "name": "demonstration"
        },
        {
            "id": 298,
            "name": "how to"
        }
    ],
    "registration_types": [
        {
            "id": 24,
            "variant_id": 1867,
            "name": "Free registration",
            "description": null,
            "stock_item": {
                "id": 17066,
                "status": "not_on_sale",
                "available": 0
            },
            "prices": [
                {
                    "decimal": "0.0",
                    "amount": 0,
                    "currency": "AUD",
                    "default": true,
                    "formatted": "$0.00"
                }
            ]
        }
    ],
    "list": {
        "id": 936655,
        "name": "Miele Australia",
        "slug": "miele-australia",
        "status": "visible",
        "permanent_list_id": 26281,
        "image": null,
        "permanent_list": {
            "id": 26281,
            "name": "Miele Australia",
            "slug": "miele-australia",
            "recurring": true,
            "status": "visible"
        },
        "setting": {
            "description": "<p>The wonders of cooking with a Miele Steam Oven await you! This relaxed, fun and informative demonstration will give you the confidence and inspiration to really get the best out of your investment.&nbsp;Watch as our experts bring to life recipes utilising the steam oven’s innovative cooking methods, learning the best ways this appliance can complement your cooking style.&nbsp;As you sit down to taste the delectable results, you’ll have all your questions answered in an intimate environment.</p>",
            "image": {
                "original": "http://app.guestmanager.com/rails/active_storage/blobs/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBaFVOIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--2e1025ef197bc7aff81eacd3f43b3fc41d2b2a84/Gourmet_Steam_Oven2.jpg"
            }
        }
    }
}
Attribute Type Description
name string Event name.
status string One of past, in_progress, future. See below for descriptions. read-only
slug string URL parameter for the event page.
venue_id integer
parent_event_id integer The recurring event this event belongs to. read-only
published_at datetime When the event was published.
position integer Sorting.
calendar_id integer Calendar this event belongs to.
start object tz, local, utc read-only
end object read-only

Event status

Status Description
past Event is over (The current time is greater than ends_at)
in_progress Event is currently running (The current time is between starts_at and ends_at)
future Event has not started yet (The current time is less than starts_at)

Event relationships

These are not included by default. To request them, add a include query parameter. You may include multiple relationships by comma separating them.

Key Relationship Type
list EventList object
company Company object
venue Venue object
categories Category array
registration_types RegistrationType array
tags Tag array

Start and end attributes

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

Attribute Type Description
tz string Venue time zone.
local string datetime in the venue time zone.
utc string datetime in UTC (global) format.

Recurring event

Recurring event object

{
    "id": 69956,
    "name": "Girls' Night In",
    "slug": "girls-night-in",
    "calendar_id": null,
    "position": 1,
    "categories": [
        {
            "id": 2,
            "name": "Complimentary Discovery Product Demonstrations",
            "subtitle": "Discover Miele",
            "position": 1,
            "short_description": "Receive expert advice to simplify your decision making process, enabling you to select the right products to empower your lifestyle",
            "description": "<p>Combining elegant new design with outstanding innovations, including ovens with smart phone style swipe or scroll touchscreens, Miele appliances are user friendly and take speed and efficiency to a whole new level – along with your cooking skills. These extraordinary appliances have so many revolutionary features and benefits, only a hands-on experience can do them justice.</p><p>Our Introductory Demonstrations are designed to allow you to sit down and relax in an intimate group as our Home Economist shows you how these ovens will transform the way you cook. We then invite you to taste the quality and range of dishes they so effortlessly produce. &nbsp;Each dish you see prepared will bring to life a feature of these amazing appliances. You’ll have all your questions answered, receive a generous helping of expert advice and leave with a selection of exclusive Miele recipes and all the inspiration you need to try them for yourself!</p><p>Please note: Cooking class attendees must be over 14 years of age.</p>",
            "image": {
                "original": "http://app.guestmanager.com/rails/active_storage/blobs/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBdmtEIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--a2e3b3e87ee9c449cb394119e8ce14edc57e90c0/Miele-Deb-Hutton-0417-exp.jpg"
            }
        }
    ],
    "tags": []
}
Field 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.

Event list

Event list object

{
  "id": 936641,
  "name": "Miele Australia",
  "slug": "miele-australia",
  "status": "visible",
  "permanent_list_id": 26281,
  "image": null,
  "links": {
    "event_page": "...",
    "order_page": "..."
  },
  "permanent_list": {
      "id": 26281,
      "name": "Miele Australia",
      "slug": "miele-australia",
      "recurring": true,
      "status": "visible"
  },
  "setting": {
      "description": "<p>This class introduces you to the world of steam, highlighting the nutritional and flavour benefits steam has to offer, while showcasing how this new generation of steam cooking can integrate into your lifestyle. &nbsp;In a comfortable setting which encourages questions, this class will equip you with the knowledge about optimal ways steam can transform the way you cook, and why you should consider this appliance as part of your kitchen design.</p>",
      "image": {
          "original": "http://app.guestmanager.com/rails/active_storage/blobs/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBaFlOIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--b0a487cb84b1e6a267e3cf27ec525dfce56d8eb2/Intro_To_Steam_GuestManager2.jpg"
  }
}
Attribute Type Description
name string List name.
slug string URL parameter for the event list.
status string One of visible or hidden
permanent_list_id integer The permanent list this event list is a part of. null for one-off lists. read-only
image object Image for the list. read-only
links object URLs for the event_page and order_page read-only

Event list relationships

Key Relationship Type
permanent_list PermanentList object
setting EventListSetting object

Category

Category object

{
    "id": 18,
    "name": "MasterClasses",
    "subtitle": null,
    "position": 3,
    "short_description": null,
    "description": null,
    "image": {
        "original": "../image.png"
    }
}
Field Type Description
name string Name of the category.
description text Description.
subtitle string Subtitle.
position integer Sorting.
short_description text Shorter description.
image object Contains URLs for the image. read-only

Ticket

Ticket object

{
    "id": 2307131,
    "number": "iZKiKsVLYB6DsSfkzAEGvmAx",
    "status": "redeemed",
    "name": "Joe Jordan",
    "email": "joe.jordan@****.co",
    "barcode": "8894042401339101",
    "note": null,
    "event_id": 68718,
    "ticket_type_id": 4329,
    "event_ticket_type_id": 13106,
    "list_id": 990493,
    "source_id": 12345,
    "source_type": "line_item",
    "contact_id": null,
    "dispatched_at": "2018-04-27T21:02:58.705838Z",
    "downloaded_at": null,
    "checkin_at": "2018-05-24T17:23:48.253518Z",
    "contact": null,
    "links": {
        "pdf": "https://client.guestmanager.com/tickets/pMWFB5ysddkNidtoJE7pfCfc.pdf",
        "wallet": null
    },
    "custom_fields": [
        {
            "id": 1605896,
            "field_id": 1504,
            "name": "Company",
            "value": "ACME Inc"
        },
        {
            "id": 1605895,
            "field_id": 1505,
            "name": "Title",
            "value": "Marketing Director"
        }
    ],
    "scans": [
        {
            "id": 606613,
            "data": "8894042401339101",
            "scanned_at": "2018-05-24T17:23:48.248922Z",
            "action": "in",
            "employee_id": 4911,
            "device_id": 3901
        }
    ],
    "emails": [
        {
            "id": 894675,
            "created_at": "2018-06-04T16:48:50.245304Z",
            "updated_at": "2018-06-04T17:04:26.582437Z",
            "type": "ticket_email",
            "email": "*****@gmail.com",
            "state": "delivered",
            "status": "opened",
            "delivery_error_detail": null,
            "click_count": 0,
            "open_count": 3,
            "subject": "Your Ticket attached!",
            "body": null
        }
    ]
}
Attribute Type Description
id int Unique identifier. read-only
event_id int ID of Event
list_id int ID of List, the event-specific list. (join table)
ticket_type_id int ID of the TicketType, a company-wide ticket type.
event_ticket_type_id int ID of the event-specific ticket type (join table)
contact_id int ID of the Contact, the owner of the ticket.
source_type string One of line_item (for Orders), rsvp, invite, or null read-only
source_id int ID of the associated source_type read-only
status string Ticket status. See below for descriptions and possible statuses. read-only
checkin_at datetime When the ticket was scanned or checked in. read-only
dispatched_at datetime When the ticket was delivered to the contact (by email) read-only
downloaded_at datetime When the contact downloaded their ticket. read-only
barcode string An event-specific barcode identifier that you can specify to scan the ticket.
number string Globally unique identifier, used to generate barcode and validate ticket (if barcode not provided). read-only
name string Name on the ticket. Usually null, when contact_id is provided.
email string Email on the ticket. Usually null, when contact_id is provided.
note string Note to display to staff at check-in.
links object Download links for PDF and Apple Wallet. PDF: links.pdf, Wallet: links.wallet read-only

Ticket status

valid and out tickets are the only statuses eligible to admit entry into an event.

Status Description
valid Ticket is valid and can be checked in or scanned.
redeemed Ticket was checked in and cannot be scanned again. See checkin_at for timestamp of when scan occurred.
out Ticket was scanned out (after having been previously redeemed)
invalidated No longer usable, but not deleted.
transferred Contact transferred ticket to another contact. No longer scan eligible. A new ticket was created and issued to replace this one.
pending When a contact creates an Order, tickets are pending until the order checkout process is completed.

Ticket relationships

Key Relationship Type Description
contact Contact object The ticket owner.
custom_fields TicketCustomField array Any custom fields specified, e.g. "Title", or "Company"
tags Tag array Tag tickets to group and track tickets according to your use case.
scans Scan array A record of every action taken on this ticket, e.g. checked in, checked out, duplicate scan, etc.
emails Email array All the emails sent out relating to this ticket.

Ticket type

A ticket type is an account wide, re-usable object.

Ticket type object

{
    "id": 7456,
    "created_at": "2019-01-07T21:56:42.755038Z",
    "updated_at": "2019-01-07T21:56:42.774215Z",
    "archived_at": null,
    "name": "GA",
    "display_name": null,
    "pdf_template_id": null,
    "wallet_template_id": null,
    "attachable": true,
    "transferable": true,
    "include_name": false,
    "include_email": false,
    "require_name": false,
    "require_email": false,
    "enforce_barcode_pool": false,
    "attachment_name": "{{ticket.name}}"
}
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).
include_name boolean false Collect a name for each ticket (applies only during order checkout or responding to an invite/RSVP)
include_email boolean false Collect an email for each ticket (applies only during order checkout or responding to an invite/RSVP)
require_name boolean false Require a name for each ticket (applies only during order checkout or responding to an invite/RSVP)
require_email boolean false Require an email for each ticket (applies only during order checkout or responding to an invite/RSVP)
enforce_barcode_pool boolean false Whether tickets can only be created if a barcode exists in the pool.
attachment_name string {{ticket.name}} How the attachment file name is formatted when including the ticket in an email.

Event ticket type

An event ticket type associates a ticket type to a specific event. Will inherit configuration from the ticket type, unless a matching attribute is overridden (pdf_template_id)

Event ticket type object

{
    "id": 19057,
    "created_at": "2019-01-07T21:56:42.769762Z",
    "updated_at": "2019-01-07T21:56:42.769762Z",
    "ticket_type_id": 7456,
    "event_id": 71389,
    "starts_at": null,
    "ends_at": null,
    "pdf_template_id": null
}
Attribute Type Description
ticket_type_id integer ID of associated ticket type. read-only
event_id integer ID of associated event. read-only
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.

Relationships

Field Type Description
ticket_type object The ticket type.

Registration types

Registration type object

{
    "id": 10,
    "variant_id": 1852,
    "name": "General admission",
    "description": "<p>description</p>",
    "stock_item": {
        "id": 17051,
        "status": "not_on_sale",
        "available": 0
    },
    "prices": [
        {
            "decimal": "0.0",
            "amount": 0,
            "currency": "AUD",
            "default": true,
            "formatted": "$0.00"
        }
    ]
}
Field Type Description
name integer
variant_id integer The linked product. Use this ID to create orders. read-only
description integer HTML description.

Relationships

Field Type Description
stock_item object Inventory details
prices array Price information

Stock item

Stock item object

{
    "id": 17051,
    "status": "not_on_sale",
    "available": 0
}
Field Type Description
id integer
status string One of selling, paused, reserve, request, not_on_sale, sold_out read-only
available integer Quantity currently in stock. read-only

Status descriptions

Price

Price object

{
    "decimal": "9.5",
    "amount": 950,
    "currency": "AUD",
    "default": true,
    "formatted": "$9.50"
}
Field Type Description
decimal string Convert this to a BigDecimal
amount integer Cents.
currency string ISO identifier for the currency.
default boolean Whether this is the default price for the product.
formatted string Friendly format for the amount, e.g. $1,250.99

Order

Order object

{
    "id": 176260,
    "number": "GM720XKYDP5SLR",
    "state": "cart",
    "checkout_steps": [
        "email",
        "register",
        "tickets",
        "address",
        "form",
        "complete"
    ],
    "contact_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
contact_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 money Grand (net) total, after adjustments, promotions, fees, and taxes. read-only
item_total money Sum of all line_item.price x line_item.quantity read-only
adjustment_total money Sum of all non-line-item charges (promotions, taxes, fees, etc). read-only
payment_total money Sum of all completed payments. read-only
additional_tax_total money Additional taxes passed onto the guest. read-only
included_tax_total money Included taxes. read-only
included_service_fee_total money Included fees. read-only
additional_service_fee_total money Extra fees passed onto the guest. read-only
promo_total money The discount on this order. read-only
shipment_total money Total shipping charges. read-only
taxable_adjustment_total money
non_taxable_adjustment_total money
application_fee_total money The fee charged by Guest Manager. 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 object 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.

Order relationships

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.
adjustments array An adjustment could be a service fee, tax, or discount. An adjustment is usually applied to a LineItem, but may also be applied directly to an order.

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.

Guest checkout properties

Add these attributes through either the create or update order endpoint. The contact_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 integer The order. 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 money per unit price.
amount money price * quantity read-only
currency string ISO code.
bundle_item_id integer The parent LineItem this LineItem is bundled under. 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

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 money 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
application_fee boolean If this amount is monies owed to Guest Manager. read-only

Payment properties

Attribute Type Description
number string Unique identifier.
amount money 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 money Monies routed to Guest Manager.
reason string A decline reason.

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.

Payment method

Attribute Type Description
type string read-only
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. read-only

Venue

Venue object

{
    "id": 0,
    "name": "Knoxfield",
    "description": null,
    "slug": "knoxfield",
    "created_at": "2016-09-19T20:35:16.794759Z",
    "updated_at": "2018-06-11T01:17:40.799858Z",
    "time_zone": "Melbourne",
    "tzinfo": {
        "name": "Melbourne",
        "identifier": "Australia/Melbourne",
        "offset": 36000,
        "formatted_offset": "+10:00"
    },
    "address": {
        "id": 78013,
        "address1": "206-210 Coventry Street",
        "city": "South Melbourne",
        "zipcode": "3205",
        "state_name": "Victoria",
        "state_code": "VIC",
        "country_name": "Australia",
        "country_code": "AU"
    }
}
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.
tzinfo object Details about the time zone. read-only

Venue relationships

Key Relationship Type
address Address object

Response

A response is a form submission, typically completed during an order checkout process.

Form response object

{
    "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

Response relationships

Key Relationship Type
answers Answer array

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

Answer relationships

Key Relationship Type
field Field object

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.

Field relationships

Key Relationship Type Description
options Option 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.

Address

Address object

{
    "id": 78013,
    "address1": "206-210 Coventry Street",
    "city": "South Melbourne",
    "zipcode": "3205",
    "state_name": "Victoria",
    "state_code": "VIC",
    "country_name": "Australia",
    "country_code": "AU"
}

For convenience, you can provide either country_code and state_code in place of country_id and state_id

Field Type Description
address1 string Line 1.
address2 string Line 2.
city string City
zipcode string Zip code / postal code.
state_name string read-only Name of the State.
state_code string Abbreviation of the State.
country_name string read-only 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 read-only State
country object read-only Country

Country

Country object

{
    "id": 3,
    "name": "Afghanistan",
    "code": "AF",
    "phone_prefix": "93",
    "currency_code": "AFN"
}
Field Type Description
name string read-only Name of the country.
code string read-only ISO code of the country.
currency_code string read-only Currency ISO code.
phone_prefix string read-only Phone prefix.

State

State object

{
    "id": 4122,
    "name": "Alabama",
    "country_id": 234,
    "code": "AL"
}
Field Type Description
name string read-only Name of the state.
code string read-only Abbreviation of the state name.
country_id integer read-only The country this state is in.

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
cURL