NAV
shell

Introduction

Welcome to the Occasion API! You can use our API to access Occasion API endpoints, which can be used to interact with all levels of functionality available to Occasion users, including: products, venues, orders, coupons, gift cards, customers, payment methods, users, calendars, etc.

We have planned language bindings in Shell, Ruby, and Javascript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Query can only be made via Shell (cURL, etc.). For a Javascript library that can be imported into your codebase, please contract the administrator.

Format

All requests and responses are in JSON format, adhering to the JSON API schema. In the examples at right, we use the readable format of URLs including [, ] and others. Note, you’ll have to format your URL to be safe before you make your request, replacing these symbols with their Unicode identifiers.

Authentication

To authorize, use this code:

# With cURL, you can make use of the -u option to create a basic authentication header
curl "api_endpoint_here"
  -u "[API_LOGIN]:[API_SECRET]"

Make sure to insert your own API login and secret keys.

Unless otherwise noted, all calls to Occasion API use HTTP basic authentication over HTTPS.

Basic authentication requires a login key and a secret key. You can find your API keys on your account page. You must be signed into your account to view this page.

Occasion requires that at the very least your API login key be provided with all queries made to our servers. Some endpoints are public, and only require an API login key. Others are private, and require that your API secret key be provided as well. Unless noted otherwise, all endpoints are public.

The data that an endpoint responds with may vary depending of whether or not a secret key was provided. For example, making a public call to GET /products will respond with a list of all your products, but any sensitive information will not be included. Making a private call (the secret key included) to the same endpoint will respond with all of your products, with all their information included. This allows you to use the API in a public environment without having to worry about any sensitive data being compromised. The difference between response bodies will be noted in the information regarding each endpoint.

Query Interface

Filtering

curl "https://app.getoccasion.com/api/v1/products?filter[price]=5"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"

Only products with price=5 will be rendered in the response.

Attaching any field/value pair of a record as a filter query parameter will allow you to filter the response by that field, responding only with records that meet your conditions.

URL Parameters

Parameter Default Description
filter[field_name]
optional
none The field to filter records by

Sorting

curl "https://app.getoccasion.com/api/v1/products?sort=updated_at"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"

Products will be sorted in ascending updated_at order.

curl "https://app.getoccasion.com/api/v1/products?sort=-updated_at,title"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"

Products will be sorted in descending updated_at order, then ascending title order

Specifying a sort parameter in your query will respond with the collection sorted by your specified field, in ascending order. Attaching a - sign in front of the value will sort in descending order.

URL Parameters

Parameter Default Description
sort
optional
-created_at The fields to sort by

Pagination

curl "https://app.getoccasion.com/api/v1/products?page[size]=5&page[number]=1"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"

Products will be paginated in groups of 5, with the second page rendered as the response.

Specifying pagination params page[size] and page[number] allows you to paginate the response of the collection you are querying.

URL Parameters

Parameter Default Description
page[size]
optional
50 The number of records per page
page[number]
optional
1 Which page of records to respond with

Fields

curl "https://app.getoccasion.com/api/v1/products?fields[products]=title,description"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"

Products will only be rendered with their title and description fields.

Specifying fields query parameters will only render those fields of the records in the response.

URL Parameters

Parameter Default Description
fields
optional
all fields (public or private) The fields to render in the response

Include

curl "https://app.getoccasion.com/api/v1/products?include=merchant,venue"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"

Products will be rendered with their merchant and venue associated records included. Example truncated for brevity.

HTTPS/1.1 200 OK
{
  "data": [
    {  
      "type": "products",
      "id": "asdj38",
      "attributes": {
        "title": "A product title",
        "description": "A product description"
      },
      "relationships": {
        "merchant": {
          "data": {
            "type": "merchants",
            "id": "lhj8we"
          }
        },
        "venue": {
          "data": {
            "type": "venues",
            "id": "jk47sh"
          }
        }
      }
    }
  ],
  "included": [
    {
      "type": "merchants",
      "id": "lhj8we",
      "attributes": {
        "name": "A Business name"
      }
    },
    {
      "type": "venues",
      "id": "jk47sh",
      "attributes": {
        "name": "Our Business Location"
      }
    }
  ]
}

Specifying include query parameters will render associations of records in the response body of each record.

URL Parameters

Parameter Default Description
include
optional
none The associations to include in the response

More Details on Modifying Query

To best understand the full power of the JSON API query interface, read the docs for it.

Merchant Scoping

If you are using the Occasion API to access your own merchant’s resources, you can skip this section. If you are an Occasion partner using the Occasion API to access other merchants’ resources, this section is relevant to you.

Occasion partners are issued credentials that require them to specify a merchant scope when making requests to resource indexes. What we mean by a merchant scope is: You can access all merchants, but if you want to access all products, it can only be for one merchant at a time. A few examples should clarify what we mean:

curl "https://app.getoccasion.com/api/v1/merchants"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"

All merchants will be returned, because you have access to all of them

curl "https://app.getoccasion.com/api/v1/products?merchant_id=jsh8e0a"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"

All products belonging to merchant with id=‘jsh8e0a’ will be returned

curl "https://app.getoccasion.com/api/v1/products"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"

400 Bad Request will be returned because you must provide a merchant_id to scope with, you cannot access all products of all merchants at once

curl "https://app.getoccasion.com/api/v1/products/37shd72"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"

Product with id='37shd72’ will be returned. No merchant scope is required because this is a request to a specific product for a specific merchant.

curl "https://app.getoccasion.com/api/v1/products?merchant_id=jsh8e0a"
  -X POST
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"

Created product belonging to merchant with id='jsh8e0a’ will be returned.

curl "https://app.getoccasion.com/api/v1/products"
  -X POST
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"

400 Bad Request will be returned because the product cannot be created without a merchant scope.

Merchants

curl "https://app.getoccasion.com/api/v1/merchants"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
{
  "data": [
    {
      "type": "merchants",
      "id": "67sdeas",
      "attributes": {
        "profile_picture": "https://app.getoccasion.com/assets/logo.jpg",
        "created_at": "2015-10-23T11:00:44.539-05:00",
        "updated_at": "2015-10-23T11:00:44.539-05:00",
        "name": "My Business Name",
        "time_zone": "America/Chicago",
        "tax_percentage": "2.0",
        "facebook_page": "https://www.facebook.com/xxxx?fref=ts"
      }
    }
  ]
}

This endpoint retrieves the merchant corresponding to your provided API credentials. If you are an Occasion API partner, this endpoint retrieves all merchants under Occasion.

HTTP Request

GET https://app.getoccasion.com/api/v1/merchants

Response Body

Notable response fields include:

Field Public Description
profile_picture true The URL for the merchant’s logo image
name true The name of the business
time_zone true The timezone that the merchant operates in
tax_percentage true The sales tax percentage that the merchant applies to each order subtotal
facebook_page true The Facebook page URL for the merchant’s business
curl "https://app.getoccasion.com/api/v1/merchants?include=business_type,currency"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
{
  "data": [
    {
      "type": "merchants",
      "id": "67sdeas",
      "attributes": {
        "profile_picture": "https://app.getoccasion.com/assets/logo.jpg",
        "created_at": "2015-10-23T11:00:44.539-05:00",
        "updated_at": "2015-10-23T11:00:44.539-05:00",
        "name": "My Business Name",
        "time_zone": "America/Chicago",
        "tax_percentage": "2.0",
        "facebook_page": "https://www.facebook.com/xxxx?fref=ts"
      },
      "relationships": {
        "business_type": {
          "data": {
            "type": "business_types",
            "id": "k87a7w"
          }
        },
        "currency": {
          "data": {
            "type": "currencies",
            "id": "7ek2ya"
          }
        }
      }
    }
  ],
  "included": [
    {
      "type": "business_types",
      "id": "k87a7w",
      "attributes": {
        "name": "Ice Rink",
      }
    },
    {
      "type": "currencies",
      "id": "7ek2ya",
      "attributes": {
        "name": "USD",
        "code": "$"
      }
    }
  ]
}

Associations

Possible associations to include are:

Association Description
business_type The type of business that the merchant is
currency The currency that the merchant accepts

Orders

Get All Orders

curl "https://app.getoccasion.com/api/v1/orders"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
{
  "data": [
    {
      "type": "orders",
      "id": "38asnd2",
      "attributes": {
        "verification_code": "kASn37a",
        "status": "booked",
        "created_at": "2015-10-23T11:00:44.539-05:00",
        "updated_at": "2015-10-23T11:00:44.539-05:00",
        "price": "15.0",
        "tax": "0.0",
        "tax_percentage": "10.0",
        "coupon_amount": "1.0",
        "coupon_description": "$1.00",
        "quantity": 1,
        "description": "This is the title of the product ordered.",
        "balance": "0.0",
        "session_identifier": "k37a8h-uw7gnc5-jqy6D0-k9287a",
        "customer_name": "Jane Smith",
        "customer_email": "jane@example.com",
        "customer_zip": "00000",
        "payment_status": "completed"
      }
    }
  ]
}

This endpoint retrieves all orders.

HTTP Request

GET https://app.getoccasion.com/api/v1/orders

Response Body

Notable response fields include:

Field Public Description
verification_code true A reference code assigned to the order after it has been completed
status true The status of the order

Possible values:
booked: Order was successfully completed and paid for.
reserved: Order was completed, and payment will be made at a later time.
dropped: The order was not successfully completed, because a payment failed.
canceled: The order was canceled and then refunded.
price true The total price of the order after tax, coupons, etc.
tax true The total sales tax for the order
tax_percentage true The sales tax percentage that was applied to the order
coupon_amount true The amount that the coupon used for this order took off from the order price
coupon_description true A readable version of the coupon amount: if a fixed discount coupon, then '$X.XX', if a percentage discount, then 'X.X%'
quantity true The quantity of this order that was purchased
description true The title of the product or order items purchased with this order
balance false The total balance of accepted transactions paid to this order
session_identifier false A unique identifier used to associate this order with a session of an order form (conversion tracking, etc.)
customer_name false The name the customer used to purchase this order
customer_email false The email the customer used to purchase this order
customer_zip false The zip code the customer used to purchase this order
payment_status false The status of the payments for this order

Possible values:
completed: Order payments were successfully completed.
awaiting_customer_payment: Customer was redirected to complete payment and we’re awaiting this completion.
processing: Payments have been made, but are still processing through providers.
failed: Payment(s) failed for some reason.

Associations

Possible associations to include are:

Association Description
attribute_values The values for attributes of the product the order is for
comments Comments made on the order by the merchant
coupon The coupon used with the order
currency The currency used to purchase the order
customer The customer that purchased the order
gift_card The gift card that may have been purchased by this order
merchant The merchant that sold this order
occurrences Occurrences of the timeslots that were purchased by the order
order_items The items purchased with the order, instead of a product
product The product that the order is for
transactions Transactions to pay for the order

Get a Specific Order

curl "https://app.getoccasion.com/api/v1/orders/38asnd2"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
{
  "data": {
    "type": "orders",
    "id": "38asnd2",
    "attributes": {
      "verification_code": "kASn37a",
      "status": "booked",
      "created_at": "2015-10-23T11:00:44.539-05:00",
      "updated_at": "2015-10-23T11:00:44.539-05:00",
      "price": "15.4",
      "tax": "1.40",
      "tax_percentage": "10.0",
      "coupon_amount": "1.0",
      "coupon_description": "$1.00",
      "quantity": 1,
      "description": "This is the title of the product ordered.",
      "balance": "0.0",
      "session_identifier": "k37a8h-uw7gnc5-jqy6D0-k9287a",
      "customer_name": "Jane Smith",
      "customer_email": "jane@example.com",
      "customer_zip": "00000",
      "payment_status": "completed"
    }
  }
}

This endpoint retrieves a specific order.

HTTP Request

GET https://app.getoccasion.com/api/v1/orders/:id

URL Parameters

Parameter Description
id The ID of the order to retrieve

Response Body

Notable response fields include:

Field Public Description
verification_code true A reference code assigned to the order after it has been completed
status true The status of the order

Possible values:
booked: Order was successfully completed and paid for.
reserved: Order was completed, and payment will be made at a later time.
dropped: The order was not successfully completed, because a payment failed.
canceled: The order was canceled and then refunded.
price true The total price of the order after tax, coupons, etc.
tax true The total sales tax for the order
tax_percentage true The sales tax percentage that was applied to the order
coupon_amount true The amount that the coupon used for this order took off from the order price
coupon_description true A readable version of the coupon amount: if a fixed discount coupon, then '$X.XX', if a percentage discount, then 'X.X%'
quantity true The quantity of this order that was purchased
description true The title of the product or order items purchased with this order
balance false The total balance of accepted transactions paid to this order
session_identifier false A unique identifier used to associate this order with a session of an order form (conversion tracking, etc.)
customer_name false The name the customer used to purchase this order
customer_email false The email the customer used to purchase this order
customer_zip false The zip code the customer used to purchase this order
payment_status false The status of the payments for this order

Possible values:
completed: Order payments were successfully completed.
awaiting_customer_payment: Customer was redirected to complete payment and we’re awaiting this completion.
processing: Payments have been made, but are still processing through providers.
failed: Payment(s) failed for some reason.

Associations

Possible associations to include are:

Association Description
attribute_values Values for attributes of the product the order is for
comments Comments made on the order by the merchant
coupon The coupon used with the order
currency The currency used to purchase the order
customer The customer that purchased the order
gift_card The gift card that may have been purchased by this order
merchant The merchant that sold this order
occurrences Occurrences of the timeslots that were purchased by the order
order_items The items purchased with the order, instead of a product
product The product that the order is for
transactions Transactions to pay for the order

Create an Order

POST /api/v1/orders HTTPS/1.1
Host: app.getoccasion.com
Authorization: Basic NTlhZTdiN2FlOWUyZTllMDFhOTUwODI5MGU1OTk=
Content-Type: application/json
{
  "data": {
    "type": "orders",
    "attributes": {
      "session_identifier": "any-unique-key",
    },
    "relationships": {
      "attribute_values": {
        "data": [
          {
            "type": "attribute_values",
            "attributes": {
              "value": "6shen2as"
            },
            "relationships": {
              "attribute": {
                "data": { "type": "attributes", "id": "12n83qa" }
              }
            }
          },
          {
            "type": "attribute_values",
            "attributes": {
              "value": "Text value"
            },
            "relationships": {
              "attribute": {
                "data": { "type": "attributes", "id": "82has32" }
              }
            }
          }
        ]
      },
      "coupon": {
        "data": { "type": "coupons", "id": "gYw6eas" }
      },
      "customer": {
        "data": {
          "type": "customers",
          "attributes": {
            "email": "jane@example.com",
            "first_name": "Jane",
            "last_name": "Smith",
            "zip": "60000"
          }
        }
      },
      "product": {
        "data": { "type": "products", "id": "bteyn26" }
      },
      "time_slots": {
        "data": [
          { "type": "time_slots", "id": "7hwq5de" },
          { "type": "time_slots", "id": "97eh2sa" }
        ]
      },
      "transactions": {
        "data": [
          {
            "type": "transactions",
            "attributes": {
              "amount": "5.0",
            },
            "relationships": {
              "payment_method": {
                "data": { "type": "credit_cards", "id": "H7gJ8GtEfCdLi88uRD6FhfrtOPTizjt" }
              }
            }
          },
          {
            "type": "transactions",
            "attributes": {
              "amount": "5.0",
            },
            "relationships": {
              "payment_method": {
                "data": { "type": "gift_cards", "id": "D3HJ8GtEfCdLixGh3D6FhfrtOPTh6w5e" }
              }
            }
          },
          {
            "type": "transactions",
            "attributes": {
              "amount": "5.0",
            },
            "relationships": {
              "payment_method": {
                "data": { "type": "paypals", "id": "3D6FhfrtOPTh6w5eH7gJ8GtEfCdL" }
              }
            }
          }
        ]
      }
    }
  }
}
HTTPS/1.1 201 Created
{
  "data": {
    "type": "orders",
    "id": "38asnd2",
    "attributes": {
      "verification_code": "kASn37a",
      "status": "booked",
      "created_at": "2015-10-23T11:00:44.539-05:00",
      "updated_at": "2015-10-23T11:00:44.539-05:00",
      "price": "10.0",
      "tax": "0.0",
      "tax_percentage": "10.0",
      "coupon_amount": "1.0",
      "coupon_description": "$1.00",
      "quantity": 1,
      "description": "This is the title of the product ordered.",
      "balance": "0.0",
      "session_identifier": "any-unique-key",
      "customer_name": "Jane Smith",
      "customer_email": "jane@example.com",
      "customer_zip": "00000",
      "payment_status": "completed"
    }
  }
}

This endpoint creates a new order

HTTP Request

POST https://app.getoccasion.com/api/v1/orders

Request Body

Field Description Required?
session_identifier An ID you can input for tracking sessions, form data, conversions, etc. false
attribute_values Values for each attribute of the product being ordered false
›attribute The attribute this attribute_value is for true
›value The value or “answer” for the attribute. If the attribute has attribute_options, this value will be the ID of the selected attribute option. Otherwise, it is just a value. true
coupon The coupon used to receive a discount on the order false
customer The customer purchasing the order true
›email The email of the customer true
›first_name The first name of the customer true
›last_name The last name of the customer true
›zip The zip of the customer true
product The product being ordered true
time_slots The time slots being ordered true
transactions The transactions (credit card, paypal, gift card) that pay for the order. The total amount paid for across transactions must equal the order price. If order has price
›amount The amount that this transaction is paying for. true
›payment_method The payment method used to purchase the transaction.

Possible types:
credit_cards
gift_cards
paypals
true

Response Body

Notable response fields include:

Field Public Description
verification_code true A reference code assigned to the order after it has been completed
status true The status of the order

Possible values:
booked: Order was successfully completed and paid for.
reserved: Order was completed, and payment will be made at a later time.
dropped: The order was not successfully completed, because a payment failed.
canceled: The order was canceled and then refunded.
price true The total price of the order after tax, coupons, etc.
tax true The total sales tax for the order
tax_percentage true The sales tax percentage that was applied to the order
coupon_amount true The amount that the coupon used for this order took off from the order price
coupon_description true A readable version of the coupon amount: if a fixed discount coupon, then '$X.XX', if a percentage discount, then 'X.X%'
quantity true The quantity of this order that was purchased
description true The title of the product or order items purchased with this order
balance false The total balance of accepted transactions paid to this order
session_identifier false A unique identifier used to associate this order with a session of an order form (conversion tracking, etc.)
customer_name false The name the customer used to purchase this order
customer_email false The email the customer used to purchase this order
customer_zip false The zip code the customer used to purchase this order
payment_status false The status of the payments for this order

Possible values:
completed: Order payments were successfully completed.
awaiting_customer_payment: Customer was redirected to complete payment and we’re awaiting this completion.
processing: Payments have been made, but are still processing through providers.
failed: Payment(s) failed for some reason.

Associations

Possible associations to include are:

Association Description
attribute_values Values for attributes of the product the order is for
comments Comments made on the order by the merchant
coupon The coupon used with the order
currency The currency used to purchase the order
customer The customer that purchased the order
gift_card The gift card that may have been purchased by this order
merchant The merchant that sold this order
occurrences Occurrences of the timeslot that the order was purchased for
order_items The items purchased with the order, instead of a product
product The product that the order is for
transactions Transactions to pay for the order

Get The Price Of An Order

POST /api/v1/orders/price HTTPS/1.1
Host: app.getoccasion.com
Authorization: Basic NTlhZTdiN2FlOWUyZTllMDFhOTUwODI5MGU1OTk=
Content-Type: application/json
{
  "data": {
    "type": "orders",
    "relationships": {
      "attribute_values": {
        "data": [
          {
            "type": "attribute_values",
            "attributes": {
              "value": "6shen2as"
            },
            "relationships": {
              "attribute": {
                "data": { "type": "attributes", "id": "12n83qa" }
              }
            }
          }
        ]
      },
      "coupon": {
        "data": { "type": "coupons", "id": "gYw6eas" }
      },
      "product": {
        "data": { "type": "products", "id": "bteyn26" }
      }
    }
  }
}
HTTPS/1.1 200 OK
{
  "data": {
    "type": "orders",
    "attributes": {
      "subtotal": "10.0",
      "coupon_amount": "1.0",
      "tax": "2.0",
      "total": "11.0"
    }
  }
}

This endpoint calculates the price of an order

HTTP Request

POST https://app.getoccasion.com/api/v1/orders/price

Request Body

Field Description Required?
attribute_values Values for the attributes that affect the price of the order false
›attribute The attribute this attribute_value is for true
›value The value or “answer” for the attribute. If the attribute has attribute_options, this value will be the ID of the selected attribute option. Otherwise, it is just a value. true
coupon The coupon that has an impact on the price of the order false
product The product that defines the base price, attributes, and tax_percentage of the order true

Response Body

Notable response fields include:

Field Description
subtotal The price of the order before adding tax or coupons. product.price + attributes
coupon_amount The amount that the coupon discounts from the order
tax The amount paid in tax, based on the tax_percentage
total The final price of the order that is to be paid by the customer

Products

Get All Products

curl "https://app.getoccasion.com/api/v1/products"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
{
  "data": [
    {
      "type": "products",
      "id": "38asnd2",
      "attributes": {
        "closing_time_relative": true,
        "created_at": "2015-10-23T11:00:44.539-05:00",
        "description": "Sign up to paint a teapot.",
        "email_subject": "Your order has been completed!",
        "from_email": "Teapot Cafe",
        "image": {
          "url": "https://s3.amazonaws.com/development.assets.playoccasion/uploads/product/image/xxxxx/xxxxx.jpg",
          "thumb": {
            "url": "https://s3.amazonaws.com/development.assets.playoccasion/uploads/product/image/xxxxx/xxxxx.jpg"
          }
        },
        "sells_sessions": true,
        "order_button_text": "Finalize order",
        "post_transactional_message": "Thank you for ordering.",
        "show_occurrence_availability": true,
        "show_time_slot_duration": false,
        "status": "active",
        "tax_percentage": "3.75",
        "time_slots_closed_before": "2000-01-01T00:00:00.000Z",
        "title": "My Art Class",
        "updated_at": "2015-10-23T11:00:44.539-05:00",
        "widget_attributes_title": "Additional Questions",
        "widget_contact_title": "Customer Information",
        "widget_occurrences_title": "Select which day you would like to reserve",
        "widget_payment_title": "Payment Information",
        "widget_total_due_title": "Total Due Today",
      }
    }
  ]
}

This endpoint retrieves all products.

HTTP Request

GET https://app.getoccasion.com/api/v1/products

Response Body

Notable response fields include:

Field Public Description
closing_time_relative true Whether or not time_slots_closed_before below indicates time relative to the time_slot start datetime, or indicates an absolute time.
description true The description for the product, explaining things in detail.
email_subject false The subject of the email that is sent after an order for this product is completed.
from_name false The from name of the email that is sent after an order for this product is completed.
image true URLs for the full image and thumbnail to display with a product.
sells_sessions true true if this product sells sessions, which means it only allows for all time slots to be purchased at once
order_button_text true The text to display in the submit button on an order widget for this product.
post_transactional_message true The message to display after an order for this product has been completed.
show_occurrence_availability true If true, show how many open seats there are for a time slot on an order widget for this product.
show_time_slot_duration true If true, display the duration of time slots on an order widget for this product.
status true The status that will determine if the product is active for ordering.

Possible values:
active: Ready to accept orders
inactive: Not accepting orders
expired: Product has time slots, but none of them are open.
sold_out: Either product or all open time slots are fully booked
tax_percentage true The sales tax percentage that is applied to an order for this product.
time_slots_closed_before true The point in time after which time slots are closed for sales. Any time slot occurring between this time and the actual occurrence of that time slot (when the class takes place) cannot be sold.
title true The title of the product, such as “BYOB & Paint A Forest”.
widget_attributes_title true The title to display above a section asking additional questions based off custom attributes.
widget_contact_title true The title to display above a section regarding customer contact information (email, first_name, last_name, zip).
widget_occurrences_title true The title to display above a section regarding choosing a time slot.
widget_payment_title true The title to display above a section asking for payment information like credit card details.
widget_total_due_title true The title to display above a section indicating the total price of the order.

Associations

Possible associations to include are:

Association Description
attributes The attributes of the product (questions to answer for an order)
merchant The merchant that the product belongs to
venue The venue that the product belongs to

Get a Specific Product

curl "https://app.getoccasion.com/api/v1/products/38asnd2"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
{
  "data": {
    "type": "products",
    "id": "38asnd2",
    "attributes": {
      "closing_time_relative": true,
      "created_at": "2015-10-23T11:00:44.539-05:00",
      "description": "Sign up to paint a teapot.",
      "email_subject": "Your order has been completed!",
      "from_email": "Teapot Cafe",
      "image": {
        "url": "https://s3.amazonaws.com/development.assets.playoccasion/uploads/product/image/xxxxx/xxxxx.jpg",
        "thumb": {
          "url": "https://s3.amazonaws.com/development.assets.playoccasion/uploads/product/image/xxxxx/xxxxx.jpg"
        }
      },
      "is_session": true,
      "order_button_text": "Finalize order",
      "post_transactional_message": "Thank you for ordering.",
      "show_occurrence_availability": true,
      "show_time_slot_duration": false,
      "status": "active",
      "tax_percentage": "3.75",
      "time_slots_closed_before": "2000-01-01T00:00:00.000Z",
      "title": "My Art Class",
      "updated_at": "2015-10-23T11:00:44.539-05:00",
      "widget_attributes_title": "Additional Questions",
      "widget_contact_title": "Customer Information",
      "widget_occurrences_title": "Select which day you would like to reserve",
      "widget_payment_title": "Payment Information",
      "widget_total_due_title": "Total Due Today",
    }
  }
}

This endpoint retrieves a specific product.

HTTP Request

GET https://app.getoccasion.com/api/v1/products/:id

URL Parameters

Parameter Description
id The ID of the product to retrieve

Response Body

Notable response fields include:

Field Public Description
closing_time_relative true Whether or not time_slots_closed_before below indicates time relative to the time_slot start datetime, or indicates an absolute time.
description true The description for the product, explaining things in detail.
email_subject false The subject of the email that is sent after an order for this product is completed.
from_name false The from name of the email that is sent after an order for this product is completed.
image true URLs for the full image and thumbnail to display with a product.
is_session true If true, the product is a session with attendees.
order_button_text true The text to display in the submit button on an order widget for this product.
post_transactional_message true The message to display after an order for this product has been completed.
show_occurrence_availability true If true, show how many open seats there are for a time slot on an order widget for this product.
show_time_slot_duration true If true, display the duration of time slots on an order widget for this product.
status true The status that will determine if the product is active for ordering.

Possible values:
active: Ready to accept orders
inactive: Not accepting orders
expired: Product has time slots, but none of them are open.
sold_out: Either product or all open time slots are fully booked
tax_percentage true The sales tax percentage that is applied to an order for this product.
time_slots_closed_before true The point in time after which time slots are closed for sales. Any time slot occurring between this time and the actual occurrence of that time slot (when the class takes place) cannot be sold.
title true The title of the product, such as “BYOB & Paint A Forest”.
widget_attributes_title true The title to display above a section asking additional questions based off custom attributes.
widget_contact_title true The title to display above a section regarding customer contact information (email, first_name, last_name, zip).
widget_occurrences_title true The title to display above a section regarding choosing a time slot.
widget_payment_title true The title to display above a section asking for payment information like credit card details.
widget_total_due_title true The title to display above a section indicating the total price of the order.

Associations

Possible associations to include are:

Association Description
attributes The attributes of the product (questions to answer for an order)
merchant The merchant that the product belongs to
venue The venue that the product belongs to

Get a Specific Product So You Can Order It

curl "https://app.getoccasion.com/api/v1/products?include=attrs.attribute_options,attrs.field_type"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
{
  "data": {
    "type": "products",
    "id": "38asnd2",
    "attributes": {
      "closing_time_relative": true,
      "created_at": "2015-10-23T11:00:44.539-05:00",
      "description": "Sign up to paint a teapot.",
      "email_subject": "Your order has been completed!",
      "from_email": "Teapot Cafe",
      "image": {
        "url": "https://s3.amazonaws.com/development.assets.playoccasion/uploads/product/image/xxxxx/xxxxx.jpg",
        "thumb": {
          "url": "https://s3.amazonaws.com/development.assets.playoccasion/uploads/product/image/xxxxx/xxxxx.jpg"
        }
      },
      "is_session": true,
      "order_button_text": "Finalize order",
      "post_transactional_message": "Thank you for ordering.",
      "show_occurrence_availability": true,
      "show_time_slot_duration": false,
      "status": "active",
      "tax_percentage": "3.75",
      "time_slots_closed_before": "2000-01-01T00:00:00.000Z",
      "title": "My Art Class",
      "updated_at": "2015-10-23T11:00:44.539-05:00",
      "widget_attributes_title": "Additional Questions",
      "widget_contact_title": "Customer Information",
      "widget_occurrences_title": "Select which day you would like to reserve",
      "widget_payment_title": "Payment Information",
      "widget_total_due_title": "Total Due Today",
    },
    "relationships": {
      "attributes": {
        "data": [
          { "type": "attributes", "id": "h6sbeekj" },
          { "type": "attributes", "id": "72yas0iu" }
        ]
      }
    }
  },
  "included": [
    {
      "type": "attributes",
      "id": "h6sbeekj",
      "attributes": {
        "title": "Which option to this question do you prefer?",
        "created_at": "2015-10-23T11:00:44.539-05:00",
        "updated_at": "2015-10-23T11:00:44.539-05:00",
        "position": 0,
        "parameters": {
        }
      },
      "relationships": {
        "attribute_options": {
          "data": [
            { "type": "attribute_options", "id": "j36ehac" },
            { "type": "attribute_options", "id": "8asbdye" }
          ]
        },
        "field_type": {
          "data": {
            "type": "field_types",
            "id": "17hejas"
          }
        }
      }
    },
    {
      "type": "attributes",
      "id": "72yas0iu",
      "attributes": {
        "title": "What input do you have?",
        "created_at": "2015-10-23T11:00:44.539-05:00",
        "updated_at": "2015-10-23T11:00:44.539-05:00",
        "position": 0,
        "parameters": {
        }
      },
      "relationships": {
        "field_type": {
          "data": {
            "type": "field_types",
            "id": "mn2l6eh"
          }
        }
      }
    },
    {
      "type": "attribute_options",
      "id": "j36ehac",
      "attributes": {
        "title": "Option 1 ($50)",
        "created_at": "2015-10-23T11:00:44.539-05:00",
        "updated_at": "2015-10-23T11:00:44.539-05:00",
        "position": 0,
        "default": true,
        "parameters": {
          "price": 50.0
        }
      }
    },
    {
      "type": "attribute_options",
      "id": "8asbdye",
      "attributes": {
        "title": "Option 2 ($100)",
        "created_at": "2015-10-23T11:00:44.539-05:00",
        "updated_at": "2015-10-23T11:00:44.539-05:00",
        "position": 1,
        "default": false,
        "parameters": {
          "price": 100.0
        }
      }
    },
    {
      "type": "field_types",
      "id": "17hejas",
      "attributes": {
        "created_at": "2015-10-23T11:00:44.539-05:00",
        "updated_at": "2015-10-23T11:00:44.539-05:00",
        "category": "price",
        "form_control": "drop_down",
        "operation": "adding",
        "reflective": false
      }
    },
    {
      "type": "field_types",
      "id": "mn2l6eh",
      "attributes": {
        "created_at": "2015-10-23T11:00:44.539-05:00",
        "updated_at": "2015-10-23T11:00:44.539-05:00",
        "category": "info",
        "form_control": "text_input",
        "operation": null,
        "reflective": false
      }
    }
  ]
}

This request retrieves a specific product with its attributes, which are needed to order the product.

HTTP Request

GET https://app.getoccasion.com/api/v1/products/:id?include=attributes.attribute_options,attributes.field_types

URL Parameters

Parameter Description
id The ID of the product to retrieve

Response Body

Notable response fields include:

Field Public Description
closing_time_relative true Whether or not time_slots_closed_before below indicates time relative to the time_slot start datetime, or indicates an absolute time.
description true The description for the product, explaining things in detail.
email_subject false The subject of the email that is sent after an order for this product is completed.
from_name false The from name of the email that is sent after an order for this product is completed.
image true URLs for the full image and thumbnail to display with a product.
is_session true If true, the product is a session with attendees.
order_button_text true The text to display in the submit button on an order widget for this product.
post_transactional_message true The message to display after an order for this product has been completed.
show_occurrence_availability true If true, show how many open seats there are for a time slot on an order widget for this product.
show_time_slot_duration true If true, display the duration of time slots on an order widget for this product.
status true The status that will determine if the product is active for ordering.

Possible values:
active: Ready to accept orders
inactive: Not accepting orders
expired: Product has time slots, but none of them are open.
sold_out: Either product or all open time slots are fully booked
tax_percentage true The sales tax percentage that is applied to an order for this product.
time_slots_closed_before true The point in time after which time slots are closed for sales. Any time slot occurring between this time and the actual occurrence of that time slot (when the class takes place) cannot be sold.
title true The title of the product, such as “BYOB & Paint A Forest”.
widget_attributes_title true The title to display above a section asking additional questions based off custom attributes.
widget_contact_title true The title to display above a section regarding customer contact information (email, first_name, last_name, zip).
widget_occurrences_title true The title to display above a section regarding choosing a time slot.
widget_payment_title true The title to display above a section asking for payment information like credit card details.
widget_total_due_title true The title to display above a section indicating the total price of the order.
attributes true The attributes of the product. Each has a value in an order for this product.
› title true The title of the attribute - the question to be answered.
› position true The position of this question in the order form
› parameters true Object containing optional parameters for the attribute
› attribute_options true Options for the attribute, if it is a drop down or other option based form control
›› title true The title of the attribute option
›› position true The position of the attribute option amongst its siblings
›› default true Whether or not this attribute option should be selected by default
›› parameters true Object containing optional parameters for the attribute option
››› price true The price of the attribute option
› field_type true The field type / form control of the attribute
›› category true What type of attribute is this: 'info', 'price', 'permutable', 'discount', 'static'
›› form_control true The form_control type for the attribute: 'text_input','drop_down','checkbox','option_list','spin_button','text_area','separator','text_output'
›› operation true The type of mathematical operation the attribute does to the price of the order: 'adding','multiplying','subtracting','dividing'
›› reflective true Whether or not this field type is one that will reflect on the value of another attribute in the product when choosing how to affect the order price.

Associations

Possible associations to include are:

Association Description
attributes The attributes of the product (questions to answer for an order)
attributes.attribute_options The options of each attribute of the product
attributes.field_type The field type for each attribute of the product
merchant The merchant that the product belongs to
venue The venue that the product belongs to

Redeemables (Coupons, Gift Cards)

Check A Possible Redeemable Code For A Product

curl "https://app.getoccasion.com/api/v1/products/:id/redeemables?filter[code]=COUPON-CODE"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
[
  {
    "data": {
      "type": "coupons",
      "id": "h17sle7",
      "attributes": {
        "name": "Holiday Coupon",
        "code": "COUPON-CODE",
        "discount_fixed": 2.0,
        "discount_percentage": null
      }
    }
  }
]
curl "https://app.getoccasion.com/api/v1/products/:id/redeemables?filter[code]=GIFT-CARD-CODE"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
[
  {
    "data": {
      "type": "gift_cards",
      "id": "h17sle7",
      "attributes": {
        "code": "GIFT-CARD-CODE",
        "initial_value": 50.0,
        "value": 5.0
      }
    }
  }
]

This endpoint requires a filter[code] that is either the code for a coupon that is available for the product, or a gift card that may be able to be used to purchase the product. Use this to check that a code is valid, and retrieve the necessary id that is required to create orders that are purchased using coupons and gift cards.

HTTP Request

GET https://app.getoccasion.com/api/v1/products/:id/redeemables?filter[code]=COUPON-OR-GIFT-CARD-CODE

URL Parameters

Parameter Description Required
id The ID of the product to retrieve redeemables for. true
filter The filter params to apply to collection of redeemables for the product. true
› code The code of the coupon or gift card that may possibly be used to purchase this product. false

Response Body

Notable response fields for coupons include:

Field Public Description
name true The name of the coupon.
code true The coupon code.
discount_fixed true The fixed cash discount for the coupon. If null, then coupon is percentage discount.
discount_percentage true The percentage discount for the coupon. If null, then coupon is fixed discount.

Notable response fields for gift_cards include:

Field Public Description
code true The gift card code.
initial_value true The initial value that was loaded onto the gift card.
value true The remaining value on the gift card.

Time Slots

Get Bookable or Upcoming Time Slots For A Product

curl "https://app.getoccasion.com/api/v1/products/:id/time_slots?filter[status]=bookable&filter[last]=k182hea&page[size]=2"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
{
  "data": [
    {
      "type": "time_slots",
      "id": "38asnd2",
      "attributes": {
        "starts_at": "2015-10-23T11:00:44.539-05:00",
        "duration": "3200",
        "spots_available": 2
      }
    },
    {
      "type": "time_slots",
      "id": "j1267fas",
      "attributes": {
        "starts_at": "2015-10-24T11:00:44.539-05:00",
        "duration": "7200",
        "spots_available": null
      }
    }
  ],
  "links": {
    "next": "https://app.getoccasion.com/api/v1/products/:id/time_slots?filter[status]=bookable&filter[last]=j1267fas&page[size]=2"
  }
}

This endpoint retrieves time slots for a product.

HTTP Request

GET https://app.getoccasion.com/api/v1/products/:id/time_slots?filter[status]=bookable&filter[last]=k182hea&page[size]=2

URL Parameters

Parameter Description Required
id The ID of the product to retrieve time slots for. true
filter The filter params to apply to collection of time slots for the product. true
› last The token of the last time slot that was in your previous time slot query. If left blank, will respond with first upcoming time slots. false
› status The status type of time slot to respond with. Only bookable or upcoming are supported. bookable returns all bookable time slots, and upcoming also includes time slots that are sold out. true
page The pagination params to apply to collection of time slots for the product. false
› size The number of time slots to respond with. Defaults to 10, max 100. false

Response Body

Notable response fields include:

Field Public Description
starts_at true The time that the time slot starts at.
duration true The duration of the time slot, in seconds.
spots_available true The number of spots available for purchase for this time slot. If null, unlimited spots available.

Venues

Get All Venues

curl "https://app.getoccasion.com/api/v1/venues"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
{
  "data": [
    {
      "type": "venues",
      "id": "n2hs7dh",
      "attributes": {
        "name": "The Playplace",
        "address": "123 Main Street",
        "city": "Chicago",
        "zip": "60614",
        "website": "www.example.com",
        "email": "admin@example.com",
        "capacity": 100,
        "phone": "(999) 999-9999",
        "public": "true",
        "time_zone": "America/Chicago"
      }
    }
  ]
}

This endpoint retrieves all venues. If made in a public context, only venues where(public: true) are returned.

HTTP Request

GET https://app.getoccasion.com/api/v1/venues

Response Body

Notable response fields include:

Field Public Description
name true The name of the venue
address true The street address of the venue
city true The city the venue is located in
zip true The ZIP code of the venue
website true The venue’s website
email true The email of the venue
capacity false The number of open orders that a venue can have for any product
phone true The phone number of the venue
public false If false, the venue should not be displayed as open for business
time_zone true The time zone that the venue operates in

Associations

Possible associations to include are:

Association Description
country The country the venue is in
state The state/province the venue is in
merchant The merchant that the venue belongs to
products All the products offered at the venue

Get a Specific Venue

curl "https://app.getoccasion.com/api/v1/venues/n2hs7dh"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
{
  "data": {
    "type": "venues",
    "id": "n2hs7dh",
    "attributes": {
      "name": "The Playplace",
      "address": "123 Main Street",
      "city": "Chicago",
      "zip": "60614",
      "website": "www.example.com",
      "email": "admin@example.com",
      "capacity": 100,
      "phone": "(999) 999-9999",
      "public": "true",
      "time_zone": "America/Chicago"
    }
  }
}

This endpoint retrieves a specific venue. If made in a public context, only a venue where(public: true) can be returned.

HTTP Request

GET https://app.getoccasion.com/api/v1/venues/:id

URL Parameters

Parameter Description
id The ID of the venue to retrieve

Response Body

Notable response fields include:

Field Public Description
name true The name of the venue
address true The street address of the venue
city true The city the venue is located in
zip true The ZIP code of the venue
website true The venue’s website
email true The email of the venue
capacity false The number of open orders that a venue can have for any product
phone true The phone number of the venue
public false If false, the venue should not be displayed as open for business
time_zone true The time zone that the venue operates in

Associations

Possible associations to include are:

Association Description
country The country the venue is in
state The state/province the venue is in
merchant The merchant that the venue belongs to
products All the products offered at the venue

Get a Specific Venue with Country and State

curl "https://app.getoccasion.com/api/v1/venues/n2hs7dh?include=country,state"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
{
  "data": {
    "type": "venues",
    "id": "n2hs7dh",
    "attributes": {
      "name": "The Playplace",
      "address": "123 Main Street",
      "city": "Chicago",
      "zip": "60614",
      "website": "www.example.com",
      "email": "admin@example.com",
      "capacity": 100,
      "phone": "(999) 999-9999",
      "public": "true",
      "time_zone": "America/Chicago"
    },
    "relationships": {
      "country": {
        "data": {
          "id": "012sje",
          "type": "countries"
        }
      },
      "state": {
        "data": {
          "id": "7s6a652",
          "type": "states"
        }
      }
    }
  },
  "included": [
    {
      "id": "012sje",
      "type": "countries",
      "attributes": {
        "name": "United States of America",
        "code": "USA"
      }
    },
    {
      "id": "7s6a652",
      "type": "states",
      "attributes": {
        "name": "Illinois",
        "code": "IL"
      }
    }
  ]
}

This endpoint retrieves a specific venue, with its country and state included. If made in a public context, only a venue where(public: true) can be returned.

HTTP Request

GET https://app.getoccasion.com/api/v1/venues/:id?include=country,state

URL Parameters

Parameter Description
id The ID of the venue to retrieve

Response Body

Notable response fields include:

Field Public Description
name true The name of the venue
address true The street address of the venue
city true The city the venue is located in
zip true The ZIP code of the venue
website true The venue’s website
email true The email of the venue
capacity false The number of open orders that a venue can have for any product
phone true The phone number of the venue
public false If false, the venue should not be displayed as open for business
time_zone true The time zone that the venue operates in

Associations

Possible associations to include are:

Association Description
country The country the venue is in
state The state/province the venue is in
merchant The merchant that the venue belongs to
products All the products offered at the venue

Errors

The Occasion API uses the following error codes:

Error Code Meaning
401 Unauthorized – Your API key(s) are wrong, or you provided insufficient credentials to a private endpoint.
404 Not Found – The specified resource could not be found.
409 Conflict – Using the resource in the attempted way conflicts with its state.
422 Unprocessable Entity – The request data could not be processed into a valid entity. (missing params, invalid format, etc.).
429 Too Many Requests – You’ve made too many requests in the last 24 hours.
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.