Catalog

Manage products and services that can be added to embeddables

📘

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

Offering Properties

PropertyTypeDescription
idstringUniquely identifies offering
namestringRequired. Name of offering. Max length 50 characters.
descriptionstringOptional. Description of offering. Max length 500 characters.
pricedecimalOptional. Price of offering. If not provided, amount will be requested at checkout time.
is_activeboolOptional. true indicates item should be shown to customers in the catalog. Default false.
service_address_requiredboolOptional. true indicates service address must be entered at checkout. Default false.
shipping_address_requiredboolOptional. true indicates shipping address must be entered at checkout. Default false.
fee_structure_idsarrayOptional. Ids of fee structures (fees, taxes, discounts or order level fees) associated with the offering.
recurrenceobjectOptional. If populated, indicates item should create a billing schedule.

Recurrence Properties

PropertyTypeDescription
frequencystringRequired. Type of recurrence. Valid values: daily, weekly, monthly, yearly
occurrencesintOptional. Indicates number of payment schedules to run. If not provided, schedule will run until suspended or cancelled.
periods_between_occurrenceintOptional. 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

PropertyTypeDescription
day_of_weekstringRequired. Valid values: sunday, monday, tuesday, wednesday, thursday, friday, saturday

Yearly Recurrence Properties

PropertyTypeDescription
monthintRequired. Month of year to run.

Monthly & Yearly Recurrence Properties

PropertyTypeDescription
day_of_month_typestringRequired. Valid options: day_of_purchase, specific_day_of_month, day_pattern.
specific_day_of_monthboolRequired when day_of_month_type is specific_day_of_month.
day_patternobjectRequired when day_of_month_type is day_pattern

Day Pattern Properties

PropertyTypeDescription
ordinalstringRequired. Valid values: last, first, second, third, fourth
daystringRequired. 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

Did this page help you?