Catalog

📘
Catalog items (products and services) are called "Offerings" in the API. Offering ids are always prefixed with "o_".

Offering Properties

Property	Type	Description
id	string	Uniquely identifies offering
name	string	Required. Name of offering. Max length 50 characters.
description	string	Optional. Description of offering. Max length 500 characters.
price	decimal	Optional. Price of offering. If not provided, amount will be requested at checkout time.
is_active	bool	Optional. `true` indicates item should be shown to customers in the catalog. Default `false`.
service_address_required	bool	Optional. `true` indicates service address must be entered at checkout. Default `false`.
shipping_address_required	bool	Optional. `true` indicates shipping address must be entered at checkout. Default `false`.
fee_structure_ids	array	Optional. Ids of fee structures (fees, taxes, discounts or order level fees) associated with the offering.
recurrence	object	Optional. If populated, indicates item should create a billing schedule.

Recurrence Properties

Property	Type	Description
frequency	string	Required. Type of recurrence. Valid values: `daily`, `weekly`, `monthly`, `yearly`
occurrences	int	Optional. Indicates number of payment schedules to run. If not provided, schedule will run until suspended or cancelled.
periods_between_occurrence	int	Optional. Indicates number of periods between schedule running. Default = 1. Example: value '2' would indicate 'every other month' when frequency is set to `monthly`.

Weekly Recurrence Properties

Property	Type	Description
day_of_week	string	Required. Valid values: `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`

Yearly Recurrence Properties

Property	Type	Description
month	int	Required. Month of year to run.

Monthly & Yearly Recurrence Properties

Property	Type	Description
day_of_month_type	string	Required. Valid options: `day_of_purchase`, `specific_day_of_month`, `day_pattern`.
specific_day_of_month	bool	Required when `day_of_month_type` is `specific_day_of_month`.
day_pattern	object	Required when `day_of_month_type` is `day_pattern`

Day Pattern Properties

Property	Type	Description
ordinal	string	Required. Valid values: `last`, `first`, `second`, `third`, `fourth`
day	string	Required. Valid values: `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `day`, `weekday`, `weekend_day`

Get Offering By Id

Request:
GET /catalog/offering/o_5b3f8823253bb36700dc3663

Response:
200 OK
{
    "data": {
        "id": "o_5b3f8823253bb36700dc3663",
        "is_active": false,
        "name": "Great Product",
        "price": 6,
        "service_address_required": false,
        "shipping_address_required": false
    }
}

Create Offering

Request (fixed price item): 
POST /catalog/offering
{
    "name": "Great Product",
    "price": 6
}

Request (price requested at checkout): 
POST /catalog/offering
{
    "name": "Great Product",
    "price": null
}

Request (recurring item with a tax, fee or line item discount):
POST /catalog/offering
{
  "name" : "Great Product",
  "price" : 5,
  "description" : "This is the one everyone will want to purchase",
  "fee_structure_ids" : [ "fs_5a83282e0915b218a0ad32da" ],
  "service_address_required": true,
  "shipping_address_required": true,
  "recurrence" : {
    "frequency": "monthly",
    "day_of_month_type": "specific_day_of_month",
    "specific_day_of_month": 12
  }
}

Response:
204 No Content

Update Offering

Request:
PUT /catalog/offering/o_5b3f8823253bb36700dc3663
{
    "name": "Great Product",
    "price": 6,
    "service_address_required": false,
    "shipping_address_required": false
}

Response:
204 No Content

Activate Offering

PUT /catalog/offering/o_5b3f8823253bb36700dc3663/activate

204 No Content

Deactivate Offering

Request:
PUT /catalog/offering/o_5b3f8823253bb36700dc3663/deactivate

Response:
204 No Content