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