Skip to content

Understory API

This is the reference documentation for the Understory API. Here you can find detailed information about the API endpoints, request and response formats, and authentication methods.

For more general information, go to Documentation.

Preview

You’re exploring an early preview of the Understory API documentation. Take a look around and see what’s available.

Want to help us test and improve it? Share your feedback by clicking the chat icon in the bottom right. We’d love to hear your thoughts!

Download OpenAPI description
index.json
index.yaml
Overview
License
Apache 2.0
Languages
Servers
https://api.understory.io

Booking

Bookings related endpoints.

Operations
Webhooks

Event Availability

Query availability for events.

Event availability is a computed value based on a number of parameters, including:

  • Event capacity and current reservations
  • Resources linked to tickets and bookings (e.g., bikes, kayaks, equipment)
  • Booking cut-off time

The availability response includes both an overall availability status and a breakdown of individual constraints, allowing you to understand exactly what factors are limiting availability for a given event.

Operations

Event

This is a preview of the Events API specification.

The API is not yet available in production.

Operations
Webhooks

Experience

This is a preview of the Experience API specification.

The API is not yet available in production.

Operations
Webhooks

Grow

This is a collection of endpoints related to Understory Grow.

Operations

Order

Orders API allows you to retrieve order information, including line items, transactions and refunds.

Operations

Get OrdersPreview

Request

Get all orders.

Security
OAuth2
Query
cursorstring

Pagination cursor for fetching the next page of results. Omit or pass an empty string to start from the beginning of the list.

limitinteger(int32)[ 1 .. 100 ]

Maximum number of items to return per page. Defaults to 100, maximum 100.

Default 100
fromstring(date-time)

Filter orders after the provided timestamp.

tostring(date-time)

Filter orders before the provided timestamp.

sortstring

Field to define the sort order. To indicate sorting direction, fields may be prefixed with + (ascending) or - (descending).

Ensure to URL escape the value as + can otherwise be interpreted as a space.

Only fields created_at and updated_at are supported.

Default "-created_at"
curl -i -X GET \
  'https://api.understory.io/v1/orders?cursor=string&limit=100&from=2019-08-24T14%3A15%3A22Z&to=2019-08-24T14%3A15%3A22Z&sort=-created_at' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
nextstring

Cursor for the next page of results. An empty string or absent value indicates the end of the list.

itemsArray of objects(Order)
idstringrequired

The unique identifier of the order.

numberstringrequired

A sequential, human-readable order number.

statusstring(OrderStatus)required

The status of the order.

Enum"PENDING""COMPLETED""CANCELLED"
payment_statusstring(PaymentStatus)required

The payment status of the order.

Enum"UNPAID""PAID""PARTIALLY_PAID""REFUNDED""PARTIALLY_REFUNDED"
created_atstring(date-time)required

Timestamp of when the order was created.

updated_atstring(date-time)required

Timestamp of when the order was last updated.

customeranyrequired

The customer that placed the order.

customer_typestring(CustomerType)required

For private customers, this is always "PRIVATE"

Enum"PRIVATE""COMPANY"
Discriminator
full_namestringrequired

The name of the customer.

emailstring(email)required

The email address of the customer.

phonestringrequired

The phone number of the customer.

addressobject(Address)required
address_linesArray of strings[ 1 .. 2 ] itemsrequired

Address lines. The first line is the primary address line, e.g. street name and number. The second line is the secondary address line, e.g. apartment number.

citystringrequired

The city of the customer.

zip_codestringrequired

The postal code of the customer.

countrystring(iso-3166-1-alpha-2)required

The country of the customer.

regionstring

The region of the customer. This can be a state, province, or other administrative region.

originanyrequired

The origin of the order.

typestringrequired

The type discriminator for booking origin.

Value"BOOKING"
Discriminator
idstringrequired

The unique identifier of the booking.

totalsobject(OrderTotals)required

Financial summary of the order.

discountobject(PriceAmount)required

The total discount applied to the order.

currencystringrequired

The ISO 4217 currency code.

Example: "USD"
valueintegerrequired

The price in the smallest currency unit (e.g. cents for USD).

Example: 2500
exponentintegerrequired

The number of decimal places for the currency.

Example: 2
vat_amountobject(PriceAmount)required

The total VAT amount for the order.

currencystringrequired

The ISO 4217 currency code.

Example: "USD"
valueintegerrequired

The price in the smallest currency unit (e.g. cents for USD).

Example: 2500
exponentintegerrequired

The number of decimal places for the currency.

Example: 2
amountobject(PriceAmount)required

The total amount for the order.

currencystringrequired

The ISO 4217 currency code.

Example: "USD"
valueintegerrequired

The price in the smallest currency unit (e.g. cents for USD).

Example: 2500
exponentintegerrequired

The number of decimal places for the currency.

Example: 2
metadataobject

A set of key-value pairs that are attached to the order for storing additional information.

property name*stringadditional property
Response
application/json
{
  "next": "string",
  "items": [
    { … }
  ]
}

Get OrderPreview

Request

Get an order by its ID.

Security
OAuth2
Path
orderIdstringrequired

The unique identifier of the order.

curl -i -X GET \
  'https://api.understory.io/v1/orders/{orderId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
idstringrequired

The unique identifier of the order.

numberstringrequired

A sequential, human-readable order number.

statusstring(OrderStatus)required

The status of the order.

Enum"PENDING""COMPLETED""CANCELLED"
payment_statusstring(PaymentStatus)required

The payment status of the order.

Enum"UNPAID""PAID""PARTIALLY_PAID""REFUNDED""PARTIALLY_REFUNDED"
created_atstring(date-time)required

Timestamp of when the order was created.

updated_atstring(date-time)required

Timestamp of when the order was last updated.

customeranyrequired

The customer that placed the order.

customer_typestring(CustomerType)required

For private customers, this is always "PRIVATE"

Enum"PRIVATE""COMPANY"
Discriminator
full_namestringrequired

The name of the customer.

emailstring(email)required

The email address of the customer.

phonestringrequired

The phone number of the customer.

addressobject(Address)required
address_linesArray of strings[ 1 .. 2 ] itemsrequired

Address lines. The first line is the primary address line, e.g. street name and number. The second line is the secondary address line, e.g. apartment number.

citystringrequired

The city of the customer.

zip_codestringrequired

The postal code of the customer.

countrystring(iso-3166-1-alpha-2)required

The country of the customer.

regionstring

The region of the customer. This can be a state, province, or other administrative region.

originanyrequired

The origin of the order.

typestringrequired

The type discriminator for booking origin.

Value"BOOKING"
Discriminator
idstringrequired

The unique identifier of the booking.

totalsobject(OrderTotals)required

Financial summary of the order.

discountobject(PriceAmount)required

The total discount applied to the order.

currencystringrequired

The ISO 4217 currency code.

Example: "USD"
valueintegerrequired

The price in the smallest currency unit (e.g. cents for USD).

Example: 2500
exponentintegerrequired

The number of decimal places for the currency.

Example: 2
vat_amountobject(PriceAmount)required

The total VAT amount for the order.

currencystringrequired

The ISO 4217 currency code.

Example: "USD"
valueintegerrequired

The price in the smallest currency unit (e.g. cents for USD).

Example: 2500
exponentintegerrequired

The number of decimal places for the currency.

Example: 2
amountobject(PriceAmount)required

The total amount for the order.

currencystringrequired

The ISO 4217 currency code.

Example: "USD"
valueintegerrequired

The price in the smallest currency unit (e.g. cents for USD).

Example: 2500
exponentintegerrequired

The number of decimal places for the currency.

Example: 2
metadataobject

A set of key-value pairs that are attached to the order for storing additional information.

property name*stringadditional property
Response
application/json
{
  "id": "string",
  "number": "string",
  "status": "PENDING",
  "payment_status": "UNPAID",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "customer": {
    "customer_type": "PRIVATE",
    "company_name": "string",
    "vat_number": "string",
    "email": "user@example.com",
    "name": "string",
    "phone": "string",
    "address": { … }
  },
  "origin": {
    "type": "BOOKING",
    "id": "string"
  },
  "totals": {
    "discount": { … },
    "vat_amount": { … },
    "amount": { … }
  },
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

Get Line ItemsPreview

Request

Get all line items for an order.

Security
OAuth2
Path
orderIdstringrequired

The unique identifier of the order.

curl -i -X GET \
  'https://api.understory.io/v1/orders/{orderId}/line-items' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
itemsArray of objects(LineItem)
quantityinteger>= 1required

The quantity of the line item.

unit_priceobject(PriceAmount)required

The unit price of the line item.

currencystringrequired

The ISO 4217 currency code.

Example: "USD"
valueintegerrequired

The price in the smallest currency unit (e.g. cents for USD).

Example: 2500
exponentintegerrequired

The number of decimal places for the currency.

Example: 2
unit_vat_amountobject(PriceAmount)required

The unit VAT amount of the line item.

currencystringrequired

The ISO 4217 currency code.

Example: "USD"
valueintegerrequired

The price in the smallest currency unit (e.g. cents for USD).

Example: 2500
exponentintegerrequired

The number of decimal places for the currency.

Example: 2
product_typestring(LineItemProductType)required

The type of product for this line item.

Enum"TICKET""GIFTCARD""TICKET_ADDON"
product_idstringrequired

The unique identifier of the product.

detailsanyrequired

Product-specific details based on the product type.

typestringrequired

The type discriminator for ticket details.

Value"TICKET"
Discriminator
experience_idstringrequired

The unique identifier of the experience.

discountobject(PriceAmount)

The discount applied to the line item.

currencystringrequired

The ISO 4217 currency code.

Example: "USD"
valueintegerrequired

The price in the smallest currency unit (e.g. cents for USD).

Example: 2500
exponentintegerrequired

The number of decimal places for the currency.

Example: 2
Response
application/json
{
  "items": [
    { … }
  ]
}

Get TransactionsPreview

Request

Get all transactions for an order.

Security
OAuth2
Path
orderIdstringrequired

The unique identifier of the order.

curl -i -X GET \
  'https://api.understory.io/v1/orders/{orderId}/transactions' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
itemsArray of objects(Transaction)
idstringrequired

The unique identifier of the transaction.

statusstring(TransactionStatus)required

The status of the transaction.

Enum"UNPAID""PAID""REFUNDED_PARTIALLY""REFUNDED_FULLY"
amountobject(PriceAmount)required

The transaction amount.

currencystringrequired

The ISO 4217 currency code.

Example: "USD"
valueintegerrequired

The price in the smallest currency unit (e.g. cents for USD).

Example: 2500
exponentintegerrequired

The number of decimal places for the currency.

Example: 2
created_atstring(date-time)required

Timestamp of when the transaction was created.

Response
application/json
{
  "items": [
    { … }
  ]
}

Get RefundsPreview

Request

Get all refunds for an order.

Security
OAuth2
Path
orderIdstringrequired

The unique identifier of the order.

curl -i -X GET \
  'https://api.understory.io/v1/orders/{orderId}/refunds' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
itemsArray of objects(Refund)
idstringrequired

The unique identifier of the refund.

statusstring(RefundStatus)required

The status of the refund.

Enum"INITIATED""COMPLETED""FAILED""CANCELLED"
amountobject(PriceAmount)required

The refund amount.

currencystringrequired

The ISO 4217 currency code.

Example: "USD"
valueintegerrequired

The price in the smallest currency unit (e.g. cents for USD).

Example: 2500
exponentintegerrequired

The number of decimal places for the currency.

Example: 2
transaction_idstringrequired

The ID of the transaction being refunded.

created_atstring(date-time)required

Timestamp of when the refund was created.

Response
application/json
{
  "items": [
    { … }
  ]
}

Test

These endpoints are for testing purposes only.

You can use them to verify that your integration authentication works as intended.

Operations

Webhook

Webhook subscription management and event delivery.

Webhooks are sent to subscriber endpoints when events occur related to experiences, events, and bookings.

Operations
Webhooks