Goody Collections API
The Collections API from Goody — 2 operation(s) for collections.
OpenAPI Specification
openapi: 3.0.1
info:
title: Goody Brands Collections API
version: 1.0.0
contact:
name: Goody Support
email: support@ongoody.com
servers:
- url: https://api.ongoody.com
description: Production
- url: https://api.sandbox.ongoody.com
description: Sandbox
tags:
- name: Collections
paths:
/v1/collections:
get:
summary: List collections
tags:
- Collections
security:
- bearer: []
parameters:
- name: page
in: query
schema:
type: integer
default: 1
minimum: 1
description: Page number for pagination (starts at 1)
required: false
- name: per_page
in: query
schema:
type: integer
default: 20
minimum: 1
maximum: 100
description: Number of collections to return per page (maximum 100)
required: false
- name: published
in: query
schema:
type: boolean
description: Return only published collections when true
required: false
responses:
'200':
description: Collections retrieved successfully
content:
application/json:
examples:
Collections retrieved successfully:
value:
data:
- id: 9afab2f9-6411-4e7f-9f7d-ecf27e00491a
workspace_id: 633e3b64-1ab4-4439-b44a-8c3a069cfd76
title: Expedite Web Enabled Infrastructures
is_published: false
published_price: null
product: null
published_version: null
- id: 7f50f2ba-e070-4e33-a107-3ddfe4c771dc
workspace_id: 633e3b64-1ab4-4439-b44a-8c3a069cfd76
title: Office Favorites
is_published: true
published_price: null
product: null
published_version:
id: 3b6af2d7-74e3-4201-8dfc-88cfacbdde91
title: Office Favorites
subtitle: Curated treats for the whole team
multiple_select_mode: disabled
multiple_select_count: null
multiple_select_price: null
international_shipping_tier: standard
international_gift_cards_enabled: false
display_interface: single_page
header_image: null
list_meta:
total_count: 2
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Collection'
list_meta:
$ref: '#/components/schemas/ListMeta'
/v1/collections/{id}:
get:
summary: Retrieve a collection
tags:
- Collections
security:
- bearer: []
parameters:
- name: id
in: path
description: Collection ID
required: true
schema:
type: string
responses:
'200':
description: Collection retrieved successfully
content:
application/json:
examples:
Collection retrieved successfully:
value:
id: 7f50f2ba-e070-4e33-a107-3ddfe4c771dc
workspace_id: 633e3b64-1ab4-4439-b44a-8c3a069cfd76
title: Office Favorites
is_published: true
published_price: null
product: null
published_version:
id: 3b6af2d7-74e3-4201-8dfc-88cfacbdde91
title: Office Favorites
subtitle: Curated treats for the whole team
multiple_select_mode: disabled
multiple_select_count: null
multiple_select_price: null
international_shipping_tier: standard
international_gift_cards_enabled: false
display_interface: single_page
header_image: null
collection_categories:
- id: ed3c56cd-d90c-4815-8caf-fd4c79b7fd46
name: Treats & Sips
is_featured: true
position: 1
collection_products:
- id: a7fe8bd9-3023-4037-8cc4-60e141f00e62
product:
id: e2b9f659-e01e-430b-aa16-14a22158cd36
name: Craft Coffee Kit
brand:
id: 7141fe00-a619-41c5-ac6a-b54342412f6d
name: Cookie Company
logo_image: null
shipping_price: 1000
free_shipping_minimum: null
brand_values: []
subtitle: null
subtitle_short: null
recipient_description: ''
variants_label: null
variants_num_selectable: null
variants: []
variant_groups: []
images: []
price: 1000
price_is_variable: false
restricted_states: []
attributes: []
updated_at: '2026-06-03T12:24:04Z'
status: active
- id: 3ceb6404-75ed-4be7-a022-e4afdf078749
product:
id: bae8372a-4325-4c5c-b58d-57e8f0a891ad
name: Artisan Snack Box
brand:
id: 7141fe00-a619-41c5-ac6a-b54342412f6d
name: Cookie Company
logo_image: null
shipping_price: 1000
free_shipping_minimum: null
brand_values: []
subtitle: null
subtitle_short: null
recipient_description: ''
variants_label: null
variants_num_selectable: null
variants: []
variant_groups: []
images: []
price: 1000
price_is_variable: false
restricted_states: []
attributes: []
updated_at: '2026-06-03T12:24:04Z'
status: active
schema:
$ref: '#/components/schemas/Collection'
'404':
description: Collection not found
content:
application/json:
examples:
Collection not found:
value:
error: Collection not found
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
CollectionProduct:
type: object
description: Represents a product that can be selected within a collection.
properties:
id:
type: string
format: uuid
product:
$ref: '#/components/schemas/Product'
required:
- id
- product
ProductVariantGroup:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
description: The name of the variant group, e.g. "Size" or "Color".
options:
type: array
items:
$ref: '#/components/schemas/ProductVariantGroupOption'
required:
- id
- name
ProductImage:
type: object
properties:
id:
type: string
format: uuid
image_large:
$ref: '#/components/schemas/Image'
required:
- id
- image_large
CollectionVersion:
type: object
description: Details about a version of a collection.
properties:
id:
type: string
format: uuid
title:
type: string
nullable: true
subtitle:
type: string
nullable: true
multiple_select_mode:
type: string
enum:
- disabled
- item_count
- max_price
description: Controls how many items recipients can select from the collection.
multiple_select_count:
type: integer
nullable: true
description: When multiple_select_mode is item_count, the number of items recipients may choose.
multiple_select_price:
type: integer
nullable: true
description: When multiple_select_mode is max_price, the spending limit in cents.
international_shipping_tier:
type: string
description: Shipping tier applied to the collection (e.g. standard, full).
international_gift_cards_enabled:
type: boolean
description: Whether international gift cards are available when swapping products.
header_image:
$ref: '#/components/schemas/Image'
nullable: true
collection_categories:
type: array
items:
$ref: '#/components/schemas/CollectionCategory'
description: Categories and their products included in this version, ordered by position.
nullable: true
required:
- id
- multiple_select_mode
- international_shipping_tier
- international_gift_cards_enabled
Product:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
brand:
$ref: '#/components/schemas/Brand'
subtitle:
type: string
nullable: true
description: A description of this product.
subtitle_short:
type: string
nullable: true
description: An optional one-line description of this product. When provided, it overrides the subtitle when displayed in areas with less space. Not always provided.
recipient_description:
type: string
nullable: true
description: An optional description of this product with custom verbiage for recipients. When provided, it overrides the subtitle for the product when displayed to the recipient. Falls back to the subtitle.
variants_label:
type: string
nullable: true
description: The label for the variants of this product, e.g. "Size" or "Color".
variants_num_selectable:
type: integer
nullable: true
description: The number of variants that can be selected for this product. For example, if this is a t-shirt, then this would be 1, since you can only select one size. If this were a build-a-box of chocolates, this could be 3 if you could select 3 flavor variants.
variants:
type: array
items:
$ref: '#/components/schemas/ProductVariant'
variant_groups:
type: array
items:
$ref: '#/components/schemas/ProductVariantGroup'
description: For products that have multiple types of variants, such as both Color and Size, this array contains each group and the options for each group. All variant group permutations have a variant generated for them, constructed from the options in the order of the groups, separated by ` / `, e.g. `Medium / Black` when the groups are Size and Color.
images:
type: array
items:
$ref: '#/components/schemas/ProductImage'
price:
type: integer
description: The price of the product, in cents.
price_is_variable:
type: boolean
description: Whether the price of this product is variable. If true, then the price can be set by the sender.
price_min:
type: integer
nullable: true
description: The minimum price of the product, in cents. Only used if price_is_variable is true.
price_max:
type: integer
nullable: true
description: The maximum price of the product, in cents. Only used if price_is_variable is true.
restricted_states:
type: array
items:
type: string
description: The US states that this product cannot be shipped to.
attributes:
type: array
items:
$ref: '#/components/schemas/ProductAttribute'
description: An array of attributes that describe this product.
status:
type: string
enum:
- active
- inactive
description: Whether this product is active. Since the product catalog only returns active products by default, this is always `true`, except if you are a Commerce API customer using a custom catalog, and are pulling products with the `custom_catalog_show_inactive` flag.
updated_at:
type: string
format: date-time
description: The date and time this product was last updated, ISO 8601 format. This is bumped when the product, brand, product variants, product attributes, or product images are updated.
reserved_options:
type: object
description: For approved API partners only.
properties:
custom_price_tier:
type: integer
nullable: true
description: For approved API partners only. A custom price tier for this product.
nullable: true
required:
- id
- name
- brand
- variants
- images
- price
- price_is_variable
- restricted_states
Brand:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
logo_image:
$ref: '#/components/schemas/Image'
nullable: true
description: The logo image for this brand.
shipping_price:
type: integer
description: The price of shipping for this brand, in cents.
free_shipping_minimum:
type: integer
description: When set and when the product price is above this amount, shipping is free. In cents. Products in a cart for this brand can combine to reach this threshold.
nullable: true
commerce_revshare_excluded:
type: boolean
description: Whether this brand is excluded from the commerce revenue share. Only displayed on the products endpoint when using a commerce app.
nullable: true
brand_values:
type: array
items:
type: string
description: An array of brand values for this brand. Potential values are USA Made, Social Impact Driven, Sustainable, Gluten Free, Vegan, Kosher Certified, Female Founded, AAPI Founded, BIPOC Founded, Black Founded, LGBTQ+ Founded, and Hispanic Founded.
brand_sets:
type: array
items:
$ref: '#/components/schemas/BrandSet'
description: An array of brand sets for this brand. Only included when using the brands endpoint.
nullable: true
required:
- id
- name
Collection:
type: object
description: A collection is a curated group of products that recipients can select from.
properties:
id:
type: string
format: uuid
workspace_id:
type: string
format: uuid
description: Workspace that owns this collection.
title:
type: string
nullable: true
is_published:
type: boolean
description: Indicates whether the collection currently has a published version.
published_price:
type: integer
nullable: true
description: Price for the published collection in cents, including shipping.
product:
$ref: '#/components/schemas/Product'
description: The product that represents the collection when published. Null for unpublished collections. To send this collection, send the product ID in the cart
nullable: true
published_version:
$ref: '#/components/schemas/CollectionVersion'
description: Details about the published version of this collection. Null for unpublished collections.
nullable: true
required:
- id
- workspace_id
- is_published
Error:
type: object
properties:
error:
type: string
required:
- error
Image:
type: object
properties:
url:
type: string
width:
type: integer
height:
type: integer
required:
- url
CollectionCategory:
type: object
description: A category of products within a collection version. All products are assigned a category.
properties:
id:
type: string
format: uuid
name:
type: string
is_featured:
type: boolean
description: Whether this category is considered the "featured" category.
position:
type: integer
collection_products:
type: array
items:
$ref: '#/components/schemas/CollectionProduct'
description: Products assigned to this category in their display order.
required:
- id
- name
- is_featured
- position
- collection_products
ProductVariant:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
image_large:
$ref: '#/components/schemas/Image'
nullable: true
subtitle:
type: string
nullable: true
required:
- id
- name
BrandSetImage:
type: object
properties:
id:
type: string
format: uuid
image_large:
$ref: '#/components/schemas/Image'
required:
- id
- image_large
BrandSet:
type: object
description: A brand set represents a collection of products from a brand.
properties:
id:
type: string
format: uuid
name:
type: string
images:
type: array
items:
$ref: '#/components/schemas/BrandSetImage'
description: An array of images for this brand set.
products:
type: array
items:
$ref: '#/components/schemas/Product'
description: An array of products in this brand set.
categories:
type: array
items:
$ref: '#/components/schemas/BrandSetCategory'
description: An array of categories this brand set belongs to.
required:
- id
- name
ProductVariantGroupOption:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
description: The name of the variant group option, e.g. "Small" for the "Size" variant group.
subtitle:
type: string
nullable: true
color:
type: string
nullable: true
description: The hex color code for this option, e.g. "#000000", if any.
image_large:
$ref: '#/components/schemas/Image'
nullable: true
required:
- id
- name
BrandSetCategory:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
subcategories:
type: array
items:
type: string
description: An array of subcategory names within this category.
required:
- id
- name
ListMeta:
type: object
properties:
total_count:
type: integer
description: The total number of items in this list.
ProductAttribute:
type: object
properties:
label:
type: string
description: The label for this attribute, e.g. "Materials".
content:
type: string
description: The content for this attribute, e.g. "80% cotton, 20% elastane". This can be text or sanitized HTML (you might choose to sanitize the HTML as well). Allowed elements are a (href allowed), div, img (src, width height, alt allowed), span, p, br, strong, b, em, i, ol, ul, li, and hr.
required:
- label
- content
securitySchemes:
bearer:
type: http
scheme: bearer
description: Your Goody API key.