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.

Right now, query can only be made via Shell (cURL, etc.), but we plan on releasing a Javascript library followed by Ruby.

Format

All responses are in JSON. All requests should be made in JSON as well. In the future, we will force requests to be in JSON format, otherwise 415 Unsupported Media Type

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 "http://app.getoccasion.com/api/v1/products?venue_id=10"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"

Only products with venue_id=10 will be rendered in the response.

Attaching any field/value pair of a record as a 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
[field_name]
optional
none The field to filter records by

Sorting

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

Products will be sorted in ascending updated_at order.

curl "http://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
id The fields to sort by

Pagination

curl "http://app.getoccasion.com/api/v1/products?per_page=5&page=1"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"

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

Specifying pagination params page and per_page allow you to paginate the response of the collection you are querying.

URL Parameters

Parameter Default Description
per_page
optional
10 The number of records per page
page
optional
0 Which page of records to respond with

Fields

curl "http://app.getoccasion.com/api/v1/products?fields=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 The fields to render in the response

Include

curl "http://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
[
  {
    "id": 1,
    "merchant_id": 10,
    "venue_id": 15,
    "merchant": {
      "id": 10,
      "name": "A Business"
    },
    "venue": {
      "id": 15,
      "name": "Our Location"
    }
  }
]

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

URL Parameters

Parameter Default Description
include
optional
varies by record model The associations to include in the response

Merchants

Based on the API credentials that Occasion issues to you, you may have access to our entire database of merchants (that have opted-in to allow you access), or you may only have access to your own merchant account. These endpoints will only return those merchants you have access to, so if the latter case is true, these endpoints will only return your own merchant account regardless of query.

If your credentials permit you to access every merchant, every query (other than /api/v1/merchants) must include a merchant_id param to filter the query by. You cannot do a top level query to /api/v1/orders, it must be /api/v1/orders?merchant_id=XX

Get All Merchants

Private call | Example truncated for brevity.

curl "https://app.getoccasion.com/api/v1/merchants"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
[{
  "id": 1,
  "profile_picture": "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",
  "net_balance": "12000.0",
  "time_zone": "America/Chicago",
  "business_type": "Skate Rink",
  "paying": true,
  "tax_percentage": "2.0",
  "free_trial_ends_at_date": "2015-10-23T11:00:44.539-05:00",
  "free_trial_volume": "1000.0",
  "free_trial_days_left": "15",
  "free_trial_volume_left": "500.0",
  "send_weekly_sales_email": true,
  "send_reminder_email": true,
  "facebook_page": "https://www.facebook.com/xxxx?fref=ts",
  "psp_id": 1,
  "psp": {
    "id": 1,
    "name": "SpreedlyPsp",
    "payment_description": "Credit Card",
    "can_refund": true
  },
  "currency": {
    "id": 1,
    "name": "USD",
    "code": "$"
  }
}]

Public call

curl "https://app.getoccasion.com/api/v1/merchants"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:"
HTTPS/1.1 200 OK
[{
  "profile_picture": "Logo.jpg",
  "name": "My Business Name",
  "time_zone": "America/Chicago",
  "tax_percentage": "2.0",
  "facebook_page": "https://www.facebook.com/xxxx?fref=ts",
  "currency": {
    "id": 1,
    "name": "USD",
    "code": "$"
  }
}]

This endpoint returns all merchants that you are authorized to access.

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
net_balance false The sum of the amounts of all cashable transactions minus the operator fees, i.e. how much money can be withdrawn to a bank account
time_zone true The timezone that the merchant operates in
business_type false The type of business that the merchant operates: 'Art Studio', 'Dance Studio', etc.
paying false Whether or not the merchant is paying for Occasion
tax_percentage true The sales tax percentage that the merchant applies to each order subtotal
free_trial_ends_at_date false The date after which the merchant must start paying to use Occasion
free_trial_volume false The sales volume that a merchant is allowed to reach before they must start paying to use Occasion
free_trial_days_left false The number of days left until the merchant must pay to continue using Occasion
free_trial_volume_left false The sales volume remaining before a merchant must pay to continue using Occasion
send_weekly_sales_email false If true, merchant will receive a weekly email summarizing their order sales
send_reminder_email false If true, merchant will send out a reminder email to customers 3 days before their booked event
facebook_page true The Facebook page URL for the merchant’s business
psp false The payment service provider that the merchant uses to process payments
▸ name The name of the PSP.

Possible values: "Cash","SpreedlyPsp",
"QantaniIdeal"
▸ payment_description The description of how payments are processed.

Possible values:
"Cash" - Merchant only accepts cash
"Credit Card" - Merchant accepts credit cards/Paypal/eCheck
"iDEAL" - Merchant accepts bank accounts through iDEAL network
▸ can_refund Whether or not the merchant can refund transactions with this PSP.

Associations

Possible associations to include are:

Association Default Public Description
psp true false The payment service provider that the merchant uses to process payments
currency true true The currency that the merchant accepts

Get A Specific Merchant

Private call

curl "https://app.getoccasion.com/api/v1/merchants/:id"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
{
  "id": 1,
  "profile_picture": "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",
  "net_balance": "12000.0",
  "time_zone": "America/Chicago",
  "business_type": "Skate Rink",
  "paying": true,
  "tax_percentage": "2.0",
  "free_trial_ends_at_date": "2015-10-23T11:00:44.539-05:00",
  "free_trial_volume": "1000.0",
  "free_trial_days_left": "15",
  "free_trial_volume_left": "500.0",
  "send_weekly_sales_email": true,
  "send_reminder_email": true,
  "facebook_page": "https://www.facebook.com/xxxx?fref=ts",
  "psp_id": 1,
  "psp": {
    "id": 1,
    "name": "SpreedlyPsp",
    "payment_description": "Credit Card",
    "can_refund": true
  },
  "currency": {
    "id": 1,
    "name": "USD",
    "code": "$"
  }
}

Public call

curl "https://app.getoccasion.com/api/v1/merchants/:id"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:"
HTTPS/1.1 200 OK
{
  "profile_picture": "Logo.jpg",
  "name": "My Business Name",
  "time_zone": "America/Chicago",
  "tax_percentage": "2.0",
  "facebook_page": "https://www.facebook.com/xxxx?fref=ts",
  "currency": {
    "id": 1,
    "name": "USD",
    "code": "$"
  }
}

This endpoint returns a specific merchant.

HTTP Request

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

URL Parameters

Parameter Description
id The ID of the merchant to retrieve

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
net_balance false The sum of the amounts of all cashable transactions minus the operator fees, i.e. how much money can be withdrawn to a bank account
time_zone true The timezone that the merchant operates in
business_type false The type of business that the merchant operates: 'Art Studio', 'Dance Studio', etc.
paying false Whether or not the merchant is paying for Occasion
tax_percentage true The sales tax percentage that the merchant applies to each order subtotal
free_trial_ends_at_date false The date after which the merchant must start paying to use Occasion
free_trial_volume false The sales volume that a merchant is allowed to reach before they must start paying to use Occasion
free_trial_days_left false The number of days left until the merchant must pay to continue using Occasion
free_trial_volume_left false The sales volume remaining before a merchant must pay to continue using Occasion
send_weekly_sales_email false If true, merchant will receive a weekly email summarizing their order sales
send_reminder_email false If true, merchant will send out a reminder email to customers 3 days before their booked event
facebook_page true The Facebook page URL for the merchant’s business
psp false The payment service provider that the merchant uses to process payments
▸ name The name of the PSP.

Possible values: "Cash","SpreedlyPsp",
"QantaniIdeal"
▸ payment_description The description of how payments are processed.

Possible values:
"Cash" - Merchant only accepts cash
"Credit Card" - Merchant accepts credit cards/Paypal/eCheck
"iDEAL" - Merchant accepts bank accounts through iDEAL network
▸ can_refund Whether or not the merchant can refund transactions with this PSP.

Associations

Possible associations to include are:

Association Default Public Description
psp true false The payment service provider that the merchant uses to process payments
currency true true The currency that the merchant accepts

Venues

Get All Venues

Private call | Example truncated for brevity.

curl "https://app.getoccasion.com/api/v1/venues"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
[
  {
    "id": 1,
    "merchant_id": 10,
    "country_id": 228,
    "state_id": 14,
    "country": {
      "id": 228,
      "name": "United States",
      "code": "US"
    },
    "state": {
      "id": 14,
      "name": "Illinois",
      "code": "IL"
    },
    "created_at": "2015-10-23T11:00:44.539-05:00",
    "updated_at": "2015-10-23T11:00:44.539-05:00",
    "time_zone": "America/Chicago",
    "name": "My Classroom",
    "email": "email@example.com",
    "address": "1111 Main Street",
    "city": "Chicago",
    "zip": "60047",
    "phone": "999-999-9999",
    "website": "www.example.com",
    "capacity": 5,
    "public": false
  }
]

Public call | Example truncated for brevity.

curl "https://app.getoccasion.com/api/v1/venues"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:"
HTTPS/1.1 200 OK
[
  {
    "country_id": 228,
    "state_id": 14,
    "country": {
      "id": 228,
      "name": "United States",
      "code": "US"
    },
    "state": {
      "id": 14,
      "name": "Illinois",
      "code": "IL"
    },
    "time_zone": "America/Chicago",
    "name": "My Classroom",
    "email": "email@example.com",
    "address": "1111 Main Street",
    "city": "Chicago",
    "zip": "60047",
    "phone": "999-999-9999",
    "website": "www.example.com"
  }
]

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
time_zone true The time zone that the venue operates in
name true The name of the venue
email true The email 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
phone true The phone number of the venue
website true The venue’s website
capacity false The number of open orders that a venue can have for any product
public false If false, the venue should not be displayed as open for business

Associations

Possible associations to include are:

Association Default Public Description
country true true The country that the venue is located in
state true true The state/province the venue is located in
products false true All the products that belong to the venue
merchant false true The merchant that the venue belongs to

Get a Specific Venue

Private call

curl "https://app.getoccasion.com/api/v1/venues/12"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
{
  "id": 1,
  "merchant_id": 10,
  "country_id": 228,
  "state_id": 14,
  "country": {
    "id": 228,
    "name": "United States",
    "code": "US"
  },
  "state": {
    "id": 14,
    "name": "Illinois",
    "code": "IL"
  },
  "created_at": "2015-10-23T11:00:44.539-05:00",
  "updated_at": "2015-10-23T11:00:44.539-05:00",
  "time_zone": "America/Chicago",
  "name": "My Classroom",
  "email": "email@example.com",
  "address": "1111 Main Street",
  "city": "Chicago",
  "zip": "60047",
  "phone": "999-999-9999",
  "website": "www.example.com",
  "capacity": 5,
  "public": false
}

Public call

curl "https://app.getoccasion.com/api/v1/venues/12"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:"
HTTPS/1.1 200 OK
{
  "country_id": 228,
  "state_id": 14,
  "country": {
    "id": 228,
    "name": "United States",
    "code": "US"
  },
  "state": {
    "id": 14,
    "name": "Illinois",
    "code": "IL"
  },
  "time_zone": "America/Chicago",
  "name": "My Classroom",
  "email": "email@example.com",
  "address": "1111 Main Street",
  "city": "Chicago",
  "zip": "60047",
  "phone": "999-999-9999",
  "website": "www.example.com"
}

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
time_zone true The time zone that the venue operates in
name true The name of the venue
email true The email 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
phone true The phone number of the venue
website true The venue’s website
capacity false The number of open orders that a venue can have for any product
public false If false, the venue should not be displayed as open for business

Associations

Possible associations to include are:

Association Default Public Description
country true true The country that the venue is located in
state true true The state/province the venue is located in
products false true All the products that belong to the venue
merchant false true The merchant that the venue belongs to

Products

Get All Products

Private call | Example truncated for brevity.

curl "https://app.getoccasion.com/api/v1/products"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
[
  {
    "id": 1,
    "merchant_id": 10,
    "venue_id": 15,
    "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"
      }
    },
    "title": "My Art Class",
    "description": "Sign up to paint a teapot.",
    "order_button_text": "Finalize order",
    "status": "active",
    "created_at": "2015-10-23T11:00:44.539-05:00",
    "updated_at": "2015-10-23T11:00:44.539-05:00",
    "token": "38asnd2",
    "post_transactional_message": "Thank you for ordering.",
    "price": "10.0",
    "time_slots_closed_before": "2000-01-01T00:00:00.000Z",
    "embed_button_text": "Book now",
    "show_occurrence_availability": true,
    "tax_percentage": "2.0",
    "widget_contact_title": "Customer Information",
    "widget_occurrences_title": "Select which day you would like to reserve",
    "widget_attributes_title": "Additional Questions",
    "widget_payment_title": "Payment Information",
    "widget_total_due_title": "Total Due Today",
    "template_id": 8195,
    "capacity": 12,
    "show_time_slot_duration": false,
    "sells_gift_cards": false,
    "widget_gift_card_recipient_title": "Gift Card Recipient",
    "gift_card_redemption_message": "To redeem your gift card, visit our website.",
    "from_name": "My Business Name",
    "email_subject": "Thanks for ordering our product!",
    "url": "http://occ.sn/p/n/sdj291"
  }
]

Public call | Example truncated for brevity.

curl "https://app.getoccasion.com/api/v1/products"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:"
HTTPS/1.1 200 OK
[
  {
    "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"
      }
    },
    "title": "My Art Class",
    "description": "Sign up to paint a teapot.",
    "order_button_text": "Finalize order",
    "status": "active",
    "post_transactional_message": "Thank you for ordering.",
    "price": "10.0",
    "time_slots_closed_before": "2000-01-01T00:00:00.000Z",
    "embed_button_text": "Book now",
    "show_occurrence_availability": true,
    "tax_percentage": "2.0",
    "widget_contact_title": "Customer Information",
    "widget_occurrences_title": "Select which day you would like to reserve",
    "widget_attributes_title": "Additional Questions",
    "widget_payment_title": "Payment Information",
    "widget_total_due_title": "Total Due Today",
    "show_time_slot_duration": false,
    "sells_gift_cards": false,
    "widget_gift_card_recipient_title": "Gift Card Recipient",
    "url": "http://occ.sn/p/n/sdj291"
  }
]

This endpoint retrieves all products.

HTTP Request

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

Response Body

Notable response fields include:

Field Public Description
image true URLs for the full image and thumbnail to display with a product
title true The title of the product, such as “BYOB & Paint A Forest”
description true The description for the product, explaining things in detail
order_button_text true The text to display in the submit order button on an order widget
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
token false The token uniquely identifying a product on Occasion, in place of ID. Cannot be used in place of ID in calls, yet, unless as GET /products?token=[token]
post_transactional_message true The message to display after an order has been completed
price true The base price of the order, before applying price changing questions, tax, coupons, gift cards, etc.
time_slots_closed_before true The point in time before which time slots are closed for sales. Any time slot occurring between Time.now and the actual occurrence of that time slot (when the class takes place) cannot be sold.
embed_button_text true The text to display in an embed button that opens an order widget
show_occurrence_availability true If true, show how many open seats there are for a time slot
tax_percentage true The sales tax percentage that is applied to the subtotal of an order for this product
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_attributes_title true The title to display above a section asking additional questions based off custom attributes
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
widget_gift_card_recipient_title true The title to display above a section asking for the details of a gift card recipient (name, email, personal message), if the product sells_gift_cards
template_id false The ID of the template product that this product has been duplicated from
capacity false The amount of orders that can be reserved (booked but having not occurred yet) for a product
show_time_slot_duration true If true, display the duration of a time slot
sells_gift_cards true If true, display the gift card attributes in an order widget and create a gift card with the order, with a value equal to the total price of the order
gift_card_redemption_message false The message to display in additional to a gift card’s personal message, typically instructing a recipient on how to redeem their gift card
from_name false The from name on the email sent to a customer after they complete an order
email_subject false The subject line on the email sent to a customer after they complete an order
url true The short URL to send someone to to purchase an order for a product

Associations

Possible associations to include are:

Association Default Public Description
merchant false true The merchant that the product belongs to
venue false true The venue that the product belongs to

Get a Specific Product

Private call

curl "https://app.getoccasion.com/api/v1/products/12"
 -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
{
 "id": 12,
 "merchant_id": 10,
 "venue_id": 15,
 "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"
   }
 },
 "title": "My Art Class",
 "description": "Sign up to paint a teapot.",
 "order_button_text": "Finalize order",
 "status": "active",
 "created_at": "2015-10-23T11:00:44.539-05:00",
 "updated_at": "2015-10-23T11:00:44.539-05:00",
 "token": "38asnd2",
 "post_transactional_message": "Thank you for ordering.",
 "price": "10.0",
 "time_slots_closed_before": "2000-01-01T00:00:00.000Z",
 "embed_button_text": "Book now",
 "show_occurrence_availability": true,
 "tax_percentage": "2.0",
 "widget_contact_title": "Customer Information",
 "widget_occurrences_title": "Select which day you would like to reserve",
 "widget_attributes_title": "Additional Questions",
 "widget_payment_title": "Payment Information",
 "widget_total_due_title": "Total Due Today",
 "template_id": 8195,
 "capacity": 12,
 "show_time_slot_duration": false,
 "sells_gift_cards": false,
 "widget_gift_card_recipient_title": "Gift Card Recipient",
 "gift_card_redemption_message": "To redeem your gift card, visit our website.",
 "from_name": "My Business Name",
 "email_subject": "Thanks for ordering our product!",
 "url": "http://occ.sn/p/n/sdj291"
}

Public call

curl "https://app.getoccasion.com/api/v1/products/12"
 -u "59a8517fd9458b46d4ee59f8fd717fb80d:"
HTTPS/1.1 200 OK
{
 "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"
   }
 },
 "title": "My Art Class",
 "description": "Sign up to paint a teapot.",
 "order_button_text": "Finalize order",
 "status": "active",
 "post_transactional_message": "Thank you for ordering.",
 "price": "10.0",
 "time_slots_closed_before": "2000-01-01T00:00:00.000Z",
 "embed_button_text": "Book now",
 "show_occurrence_availability": true,
 "tax_percentage": "2.0",
 "widget_contact_title": "Customer Information",
 "widget_occurrences_title": "Select which day you would like to reserve",
 "widget_attributes_title": "Additional Questions",
 "widget_payment_title": "Payment Information",
 "widget_total_due_title": "Total Due Today",
 "show_time_slot_duration": false,
 "sells_gift_cards": false,
 "widget_gift_card_recipient_title": "Gift Card Recipient",
 "url": "http://occ.sn/p/n/sdj291"
}

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 elements include:

Field Public Description
image true URLs for the full image and thumbnail to display with a product
title true The title of the product, such as “BYOB & Paint A Forest”
description true The description for the product, explaining things in detail
order_button_text true The text to display in the submit order button on an order widget
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
token false The token uniquely identifying a product on Occasion, in place of ID. Cannot be used in place of ID in calls, yet, unless as GET /products?token=[token]
post_transactional_message true The message to display after an order has been completed
price true The base price of the order, before applying price changing questions, tax, coupons, gift cards, etc.
time_slots_closed_before true The point in time before which time slots are closed for sales. Any time slot occurring between Time.now and the actual occurrence of that time slot (when the class takes place) cannot be sold.
embed_button_text true The text to display in an embed button that opens an order widget
show_occurrence_availability true If true, show how many open seats there are for a time slot
tax_percentage true The sales tax percentage that is applied to the subtotal of an order for this product
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_attributes_title true The title to display above a section asking additional questions based off custom attributes
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
widget_gift_card_recipient_title true The title to display above a section asking for the details of a gift card recipient (name, email, personal message), if the product sells_gift_cards
template_id false The ID of the template product that this product has been duplicated from
capacity false The amount of orders that can be reserved (booked but having not occurred yet) for a product
show_time_slot_duration true If true, display the duration of a time slot
sells_gift_cards true If true, display the gift card attributes in an order widget and create a gift card with the order, with a value equal to the total price of the order
gift_card_redemption_message false The message to display in additional to a gift card’s personal message, typically instructing a recipient on how to redeem their gift card
from_name false The from name on the email sent to a customer after they complete an order
email_subject false The subject line on the email sent to a customer after they complete an order
url true The short URL to send someone to to purchase an order for a product

Associations

Possible associations to include are:

Association Default Public Description
merchant false true The merchant that the product belongs to
venue false true The venue that the product belongs to

Orders

Get All Orders

Private call | Example truncated for brevity.

curl "https://app.getoccasion.com/api/v1/orders"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
[
  {
    "id": 1,
    "customer_id": 10,
    "verification_code": "20S39A",
    "status": "booked",
    "created_at": "2015-10-23T11:00:44.539-05:00",
    "updated_at": "2015-10-23T11:00:44.539-05:00",
    "merchant_id": 5,
    "currency_id": 1,
    "occurrence_id": 32923,
    "product_id": 3092,
    "price": "10.0",
    "balance": "0.0",
    "quantity": 5,
    "summary": "",
    "session_identifier": "kejas-1s2kb-n2fha-37sba",
    "coupon_id": 203,
    "coupon_amount": "5.0",
    "coupon_description": "",
    "description": "My product",
    "quickorder": false,
    "tax_percentage": "0.0",
    "referrer_id": null,
    "customer_name": "John Smith",
    "customer_email": "john@example.com",
    "customer_zip": "00000",
    "payment_status": "completed"
  }
]

Public call | Example truncated for brevity.

curl "https://app.getoccasion.com/api/v1/orders"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:"
HTTPS/1.1 200 OK
[
  {
    "id": 1,
    "customer_id": 10,
    "verification_code": "20S39A",
    "status": "booked",
    "created_at": "2015-10-23T11:00:44.539-05:00",
    "updated_at": "2015-10-23T11:00:44.539-05:00",
    "merchant_id": 5,
    "currency_id": 1,
    "occurrence_id": 32923,
    "product_id": 3092,
    "price": "10.0",
    "quantity": 5,
    "summary": "",
    "coupon_id": 203,
    "coupon_amount": "5.0",
    "coupon_description": "",
    "description": "My product",
    "tax_percentage": "0.0",
    "referrer_id": null,
    "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 The verification code for the order
status true The status of the order.

Possible values:
reserved: Order made, waiting for payment / payment processing
dropped: Payment failed
booked: Order completed, payment received or no payment required
canceled: Order canceled by merchant
price true The total price for this order
balance false The amount of the order that has been paid
quantity true The amount of availability slots booked in this order
summary true A text block representing a summary of all the options selected by the customer
session_identifier false A unique identifier generated each time the order widget is loaded, to prevent duplicate orders
coupon_amount true The decimal amount that the coupon of this order deducted from the price
coupon_description true The readable description of the coupon amount (-$10.00, 10.00%)
description true The product title that offers a description of the order
quickorder false Whether or not this order was made using the merchant’s backend quickorder panel
tax_percentage true The percentage tax applied to the order
referrer_id true The ID of the order that was used to refer the customer that booked this order
payment_status true The status of the payments for this order

Possible values:
completed: Sum of payments is equal to order price
awaiting_customer_payment: Customer still needs to initiate a payment
processing: Customer initiated a payment that is still processing
failed: Customer initiated a payment that has failed during processing
unknown: The status of payments is not known

Associations

Possible associations to include are:

Association Public Description
currency true The currency the order was purchased in
occurrence true A single availability occurrence of the time_slot booked (a time_slot may have multiple occurrences)
coupon true The coupon that was used when purchasing this order
customer true The customer that purchased this order
merchant true The merchant that sold this order
product true The product listing that this order is for
attribute_values true The options selected by the customer for each individual attribute
transactions true The transactions that have paid out this order (or refunded it)
comments true Notes the merchant has made to the order for their own internal use

Get a Specific Order

Private call | Example truncated for brevity.

curl "https://app.getoccasion.com/api/v1/orders/:id"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:de7b7ae9e2e9e01a9508290e599"
HTTPS/1.1 200 OK
{
  "id": 1,
  "customer_id": 10,
  "verification_code": "20S39A",
  "status": "booked",
  "created_at": "2015-10-23T11:00:44.539-05:00",
  "updated_at": "2015-10-23T11:00:44.539-05:00",
  "merchant_id": 5,
  "currency_id": 1,
  "occurrence_id": 32923,
  "product_id": 3092,
  "price": "10.0",
  "balance": "0.0",
  "quantity": 5,
  "summary": "",
  "session_identifier": "posa2l-1464336107064",
  "coupon_id": 203,
  "coupon_amount": "5.0",
  "coupon_description": "",
  "description": "My product",
  "quickorder": false,
  "tax_percentage": "0.0",
  "referrer_id": null,
  "customer_name": "John Smith",
  "customer_email": "john@example.com",
  "customer_zip": "00000",
  "payment_status": "completed"
}

Public call | Example truncated for brevity.

curl "https://app.getoccasion.com/api/v1/orders/:id"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:"
HTTPS/1.1 200 OK
{
  "id": 1,
  "customer_id": 10,
  "verification_code": "20S39A",
  "status": "booked",
  "created_at": "2015-10-23T11:00:44.539-05:00",
  "updated_at": "2015-10-23T11:00:44.539-05:00",
  "merchant_id": 5,
  "currency_id": 1,
  "occurrence_id": 32923,
  "product_id": 3092,
  "price": "10.0",
  "quantity": 5,
  "summary": "",
  "coupon_id": 203,
  "coupon_amount": "5.0",
  "coupon_description": "",
  "description": "My product",
  "tax_percentage": "0.0",
  "referrer_id": null,
  "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 The verification code for the order
status true The status of the order.

Possible values:
reserved: Order made, waiting for payment / payment processing
dropped: Payment failed
booked: Order completed, payment received or no payment required
canceled: Order canceled by merchant
price true The total price for this order
balance false The amount of the order that has been paid
quantity true The amount of availability slots booked in this order
summary true A text block representing a summary of all the options selected by the customer
session_identifier false A unique identifier generated each time the order widget is loaded, to prevent duplicate orders
coupon_amount true The decimal amount that the coupon of this order deducted from the price
coupon_description true The readable description of the coupon amount (-$10.00, 10.00%)
description true The product title that offers a description of the order
quickorder false Whether or not this order was made using the merchant’s backend quickorder panel
tax_percentage true The percentage tax applied to the order
referrer_id true The ID of the order that was used to refer the customer that booked this order
payment_status true The status of the payments for this order

Possible values:
completed: Sum of payments is equal to order price
awaiting_customer_payment: Customer still needs to initiate a payment
processing: Customer initiated a payment that is still processing
failed: Customer initiated a payment that has failed during processing
unknown: The status of payments is not known

Associations

Possible associations to include are:

Association Public Description
currency true The currency the order was purchased in
occurrence true A single availability occurrence of the time_slot booked (a time_slot may have multiple occurrences)
coupon true The coupon that was used when purchasing this order
customer true The customer that purchased this order
merchant true The merchant that sold this order
product true The product listing that this order is for
attribute_values true The options selected by the customer for each individual attribute
transactions true The transactions that have paid out this order (or refunded it)
comments true Notes the merchant has made to the order for their own internal use

Create an Order

POST /api/v1/orders HTTPS/1.1
Host: app.getoccasion.com
Authorization: Basic fdQWxhZGRpbjpvcd4ee59f8GVuIHNlc2==
Content-Type: application/json
{
  "order": {
    "merchant_id": 5,
    "product_id": 3092,
    "customer_id": 10,
    "session_identifier": "posa2l-1464336107064",
    "time_slot_id": "210120392919",
    "payment_method_token": "12an38cbag3klbh2g1mdkajm4ah2jvtd8a",
    "attribute_values": [
      {
        "attr_id": 15,
        "value": "YES"
      },
      {
        "attr_id": 16,
        "value": "20"
      }
    ]
  }
}
HTTPS/1.1 201 Created
{
  "id": 1,
  "customer_id": 10,
  "verification_code": "20S39A",
  "status": "booked",
  "created_at": "2015-10-23T11:00:44.539-05:00",
  "updated_at": "2015-10-23T11:00:44.539-05:00",
  "merchant_id": 5,
  "currency_id": 1,
  "occurrence_id": 32923,
  "product_id": 3092,
  "price": "10.0",
  "balance": "10.0",
  "quantity": 5,
  "summary": "",
  "session_identifier": "posa2l-1464336107064",
  "coupon_id": null,
  "coupon_amount": null,
  "coupon_description": null,
  "description": "My product",
  "quickorder": false,
  "tax_percentage": "0.0",
  "referrer_id": null,
  "customer_name": "John Smith",
  "customer_email": "john@example.com",
  "customer_zip": "00000",
  "payment_status": "completed"
}

Public call | Example truncated for brevity.

curl "https://app.getoccasion.com/api/v1/orders/:id"
  -u "59a8517fd9458b46d4ee59f8fd717fb80d:"
HTTPS/1.1 200 OK
{
  "id": 1,
  "customer_id": 10,
  "verification_code": "20S39A",
  "status": "booked",
  "created_at": "2015-10-23T11:00:44.539-05:00",
  "updated_at": "2015-10-23T11:00:44.539-05:00",
  "merchant_id": 5,
  "currency_id": 1,
  "occurrence_id": 32923,
  "product_id": 3092,
  "price": "10.0",
  "quantity": 5,
  "summary": "",
  "coupon_id": null,
  "coupon_amount": null,
  "coupon_description": null,
  "description": "My product",
  "tax_percentage": "0.0",
  "referrer_id": null,
  "payment_status": "completed"
}

This endpoint creates a new order

HTTP Request

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

Request Body

Parameter Description
merchant_id The ID of the merchant that is selling this order
product_id The ID of the product this order is for
customer_id The ID of the customer booking this order
session_identifier A unique identifier to distinguish a session of the order widget from all others (prevents duplicate orders)
time_slot_id The ID of the time slot the customer is booking
payment_method_token The token for the payment method the customer is using to purchase this order
attribute_values The options selected for each attribute of the order

Response Body

Notable response fields include:

Field Public Description
verification_code true The verification code for the order
status true The status of the order.

Possible values:
reserved: Order made, waiting for payment / payment processing
dropped: Payment failed
booked: Order completed, payment received or no payment required
canceled: Order canceled by merchant
price true The total price for this order
balance false The amount of the order that has been paid
quantity true The amount of availability slots booked in this order
summary true A text block representing a summary of all the options selected by the customer
session_identifier false A unique identifier generated each time the order widget is loaded, to prevent duplicate orders
coupon_amount true The decimal amount that the coupon of this order deducted from the price
coupon_description true The readable description of the coupon amount (-$10.00, 10.00%)
description true The product title that offers a description of the order
quickorder false Whether or not this order was made using the merchant’s backend quickorder panel
tax_percentage true The percentage tax applied to the order
referrer_id true The ID of the order that was used to refer the customer that booked this order
payment_status true The status of the payments for this order

Possible values:
completed: Sum of payments is equal to order price
awaiting_customer_payment: Customer still needs to initiate a payment
processing: Customer initiated a payment that is still processing
failed: Customer initiated a payment that has failed during processing
unknown: The status of payments is not known

Associations

Possible associations to include are:

Association Public Description
currency true The currency the order was purchased in
occurrence true A single availability occurrence of the time_slot booked (a time_slot may have multiple occurrences)
coupon true The coupon that was used when purchasing this order
customer true The customer that purchased this order
merchant true The merchant that sold this order
product true The product listing that this order is for
attribute_values true The options selected by the customer for each individual attribute
transactions true The transactions that have paid out this order (or refunded it)
comments true Notes the merchant has made to the order for their own internal use

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.