Goody Collections API

openapi: 3.2.0
info:
  title: Goody 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
      - name: workspace_id
        in: query
        schema:
          type: string
          format: uuid
        description: Return only collections in this workspace. Must be a workspace the caller belongs to.
        required: false
      - name: exclude_archived
        in: query
        schema:
          type: boolean
        description: Exclude archived collections when true
        required: false
      responses:
        '200':
          description: Collections retrieved successfully
          content:
            application/json:
              examples:
                Collections retrieved successfully:
                  value:
                    data:
                    - id: 0d84aaff-5897-4dad-9730-7ffa3d22d8af
                      workspace_id: bb1e1eec-1639-4dd4-b59e-0556704e2c6c
                      title: Monetize Bleeding Edge Interfaces
                      is_published: false
                      published_price: null
                      products_count: null
                      product: null
                      published_version: null
                    - id: b0e0a375-1608-4a80-8742-ef119280bdfb
                      workspace_id: bb1e1eec-1639-4dd4-b59e-0556704e2c6c
                      title: Office Favorites
                      is_published: true
                      published_price: null
                      products_count: 2
                      product: null
                      published_version:
                        id: 5cff2c76-2e35-42c2-90eb-6d960e83533a
                        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'
      operationId: getV1Collections
      x-operation-id-source: derived
  /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: b0e0a375-1608-4a80-8742-ef119280bdfb
                    workspace_id: bb1e1eec-1639-4dd4-b59e-0556704e2c6c
                    title: Office Favorites
                    is_published: true
                    published_price: null
                    products_count: 2
                    product: null
                    published_version:
                      id: 5cff2c76-2e35-42c2-90eb-6d960e83533a
                      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: 2f3424fd-c84a-4377-af94-b615b7356783
                        name: Treats & Sips
                        is_featured: true
                        position: 1
                        collection_products:
                        - id: c40eea45-81b0-4147-a189-80f871e367d3
                          product:
                            id: 45f6d715-eb8e-4e34-b2b8-1142b3b8e3dd
                            name: Craft Coffee Kit
                            brand:
                              id: 4d810f66-85a3-416a-b7cb-58cc0784b56e
                              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
                            cart_eligible: true
                            price_min: 1000
                            price_max: 1000
                            gift_card: null
                            restricted_states: []
                            shipping_country_group:
                              domestic:
                              - US
                              global: []
                              gift_card: []
                            attributes: []
                            updated_at: '2026-07-28T20:20:04Z'
                            status: active
                        - id: f072b0a8-b80a-4da1-a217-1a8c20db1e66
                          product:
                            id: 6207980d-8555-419e-9fb4-2c46411cdfce
                            name: Artisan Snack Box
                            brand:
                              id: 4d810f66-85a3-416a-b7cb-58cc0784b56e
                              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
                            cart_eligible: true
                            price_min: 1000
                            price_max: 1000
                            gift_card: null
                            restricted_states: []
                            shipping_country_group:
                              domestic:
                              - US
                              global: []
                              gift_card: []
                            attributes: []
                            updated_at: '2026-07-28T20:20: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'
      operationId: getV1CollectionsById
      x-operation-id-source: derived
components:
  schemas:
    Brand:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        logo_image:
          $ref: '#/components/schemas/Image'
          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
          - 'null'
          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.
        commerce_revshare_excluded:
          type:
          - boolean
          - 'null'
          description: Whether this brand is excluded from the commerce revenue share. Only displayed on the products endpoint when using a commerce app.
        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.
        subtitle:
          type:
          - string
          - 'null'
          description: A short marketing description of the brand. Only included when using the brands endpoint.
        tile_image:
          $ref: '#/components/schemas/Image'
          description: The square tile image for this brand. Only included when using the brands endpoint.
        header_image:
          $ref: '#/components/schemas/Image'
          description: The wide header image for this brand. Only included when using the brands endpoint.
        price_min:
          type:
          - integer
          - 'null'
          description: The lowest product price among this brand's listed products, in cents. Only included when using the brands endpoint.
        brand_sets:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/BrandSet'
          description: An array of brand sets for this brand. Only included when using the brands endpoint.
      required:
      - id
      - name
    ProductImage:
      type: object
      properties:
        id:
          type: string
          format: uuid
        image_large:
          $ref: '#/components/schemas/Image'
      required:
      - id
      - image_large
    ListMeta:
      type: object
      properties:
        total_count:
          type: integer
          description: The total number of items in this list.
    Product:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        brand:
          $ref: '#/components/schemas/Brand'
        subtitle:
          type:
          - string
          - 'null'
          description: A description of this product.
        subtitle_short:
          type:
          - string
          - 'null'
          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
          - 'null'
          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
          - 'null'
          description: The label for the variants of this product, e.g. "Size" or "Color".
        variants_num_selectable:
          type:
          - integer
          - 'null'
          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
          - 'null'
          description: The minimum price of the product, in cents. Only used if price_is_variable is true.
        price_max:
          type:
          - integer
          - 'null'
          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.
        cart_eligible:
          type: boolean
          description: Whether this product can be combined with others in a single gift. False for products that must be sent on their own, such as gift cards, alcohol, custom stores, gift of choice, and collections.
        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
          - 'null'
          description: For approved API partners only.
          properties:
            custom_price_tier:
              type:
              - integer
              - 'null'
              description: For approved API partners only. A custom price tier for this product.
        gift_card:
          type:
          - object
          - 'null'
          description: Present only for gift card products. Use to tell a gift card apart from a variable-price flex gift and to enforce its amount rules. All amounts here are in the card's native currency (the units a gift card's `variable_price` is spent in).
          properties:
            currency:
              type:
              - string
              - 'null'
              description: The gift card currency, e.g. "USD".
            currency_rate:
              type:
              - number
              - 'null'
              description: Native currency units per USD (native_amount / currency_rate = USD amount), for showing the USD a sender pays on a non-USD card. Always 1 for USD; null when the rate is temporarily unavailable, in which case treat the amount as native-only.
            denominations:
              type:
              - array
              - 'null'
              items:
                type: integer
              description: The fixed set of allowed amounts, in native-currency cents. Null when the gift card is a sliding scale, in which case use value_restrictions.
            value_restrictions:
              type:
              - object
              - 'null'
              description: For a sliding-scale gift card, the inclusive native-currency-cent bounds a sender may fund. Null for fixed-denomination cards (use denominations instead).
              properties:
                min:
                  type: integer
                  description: Minimum fundable amount, in native-currency cents.
                max:
                  type: integer
                  description: Maximum fundable amount, in native-currency cents.
              required:
              - min
              - max
      required:
      - id
      - name
      - brand
      - variants
      - images
      - price
      - price_is_variable
      - restricted_states
      - cart_eligible
    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
    CollectionVersion:
      type: object
      description: Details about a version of a collection.
      properties:
        id:
          type: string
          format: uuid
        title:
          type:
          - string
          - 'null'
        subtitle:
          type:
          - string
          - 'null'
        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
          - 'null'
          description: When multiple_select_mode is item_count, the number of items recipients may choose.
        multiple_select_price:
          type:
          - integer
          - 'null'
          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'
        collection_categories:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CollectionCategory'
          description: Categories and their products included in this version, ordered by position.
      required:
      - id
      - multiple_select_mode
      - international_shipping_tier
      - international_gift_cards_enabled
    ProductVariant:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        image_large:
          $ref: '#/components/schemas/Image'
        subtitle:
          type:
          - string
          - 'null'
      required:
      - id
      - name
    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
    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
    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
    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
          - 'null'
        is_published:
          type: boolean
          description: Indicates whether the collection currently has a published version.
        published_price:
          type:
          - integer
          - 'null'
          description: Price for the published collection in cents, including shipping.
        products_count:
          type:
          - integer
          - 'null'
          description: Number of products in the published version. Null for unpublished collections.
        product:
          $ref: '#/components/schemas/ProductCartSummary'
          description: The product that represents the collection when published. Null for unpublished collections. To send this collection, send the product ID in the cart
        published_version:
          $ref: '#/components/schemas/CollectionVersion'
          description: Details about the published version of this collection. Null for unpublished collections.
      required:
      - id
      - workspace_id
      - is_published
    BrandSetImage:
      type: object
      properties:
        id:
          type: string
          format: uuid
        image_large:
          $ref: '#/components/schemas/Image'
      required:
      - id
      - image_large
    ProductCartSummary:
      type: object
      description: 'A compact product shape for products that ride along as a ready-made cart line (such as the product representing a collection): just enough to add it to a cart and render the row.'
      properties:
        id:
          type: string
          format: uuid
          description: Product ID — send it as a cart item like any other product.
        name:
          type: string
        brand:
          $ref: '#/components/schemas/Brand'
        price:
          type: integer
          description: The price of the product, in cents.
        cart_eligible:
          type: boolean
          description: Whether this product can be combined with others in a single gift. False for collections, which are always sent on their own.
        is_collection:
          type: boolean
          description: Whether this product is a collection. Collections carry their own recipient-experience settings (multi-select, shipping), so batch-level swap and international options do not apply to them.
        image_url:
          type:
          - string
          - 'null'
          description: A thumbnail image URL for the product.
      required:
      - id
      - name
      - brand
      - price
      - cart_eligible
      - is_collection
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    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
    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
    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
          - 'null'
        color:
          type:
          - string
          - 'null'
          description: The hex color code for this option, e.g. "#000000", if any.
        image_large:
          $ref: '#/components/schemas/Image'
      required:
      - id
      - name
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: Your Goody API key.
x-provenance:
  method: harvested
  publisher: Goody
  source: https://assets.ongoody.com/static/web/goody-api-openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)