Goody Products API

openapi: 3.2.0
info:
  title: Goody Products 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: Products
paths:
  /v1/products:
    get:
      summary: List all active products
      tags:
      - Products
      security:
      - bearer: []
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          default: 1
          minimum: 1
        description: Page for pagination, starting at 1
        required: false
      - name: per_page
        in: query
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 100
        description: Items per page for pagination
        required: false
      - name: use_custom_catalog
        in: query
        schema:
          type: boolean
        description: Limit to custom catalog only (for approved API partners)
        required: false
      - name: country_code
        in: query
        schema:
          type: string
          default: US
        description: Filter by a specific shipping country code
        required: false
      - name: custom_catalog_show_inactive
        in: query
        schema:
          type: boolean
        description: Show inactive products in the custom catalog. Only for Commerce API customers with a custom catalog.
        required: false
      - name: brand_id
        in: query
        schema:
          type: string
        description: Limit to products from a specific brand
        required: false
      - name: category_id
        in: query
        schema:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
        description: Limit to products in a category (see the categories endpoint). Accepts a single ID or an array of IDs.
        required: false
      - name: min_price
        in: query
        schema:
          type: integer
          minimum: 0
        description: Limit to products priced at or above this amount, in cents
        required: false
      - name: max_price
        in: query
        schema:
          type: integer
          minimum: 0
        description: Limit to products priced at or below this amount, in cents
        required: false
      - name: brand_values
        in: query
        schema:
          type: array
          items:
            type: string
        description: Limit to products whose brand has at least one of these brand values (e.g. Sustainable, Female Founded)
        required: false
      responses:
        '200':
          description: Products retrieved
          content:
            application/json:
              examples:
                Products retrieved:
                  value:
                    data:
                    - id: 7d560507-26e8-4042-9fd2-382698db4d8f
                      name: Cookie Box
                      brand:
                        id: 939d0a1d-d461-4fce-b911-4fa37ddb71eb
                        name: Jeremiah Haag PhD
                        logo_image: null
                        shipping_price: 1000
                        free_shipping_minimum: null
                        brand_values:
                        - Sustainable
                      subtitle: null
                      subtitle_short: null
                      recipient_description: ''
                      variants_label: option
                      variants_num_selectable: 1
                      variants:
                      - id: 49dbe73a-40c8-45ce-a817-9aff732d1e01
                        name: Grey / Chocolate Chip
                        subtitle: null
                        image_large: null
                      - id: 0d13f069-0fac-4b8f-9d2f-73f75255f3c8
                        name: Grey / Oatmeal
                        subtitle: null
                        image_large: null
                      - id: 6fb84f13-2ea9-4d6b-9bba-02d557ccd277
                        name: Grey / Sugar
                        subtitle: null
                        image_large: null
                      - id: 17fd1615-4c2b-4dff-b208-c8c37e533ee4
                        name: Purple / Chocolate Chip
                        subtitle: null
                        image_large: null
                      - id: 2d82b15b-3732-475c-943a-80e7ce95ca2c
                        name: Purple / Oatmeal
                        subtitle: null
                        image_large: null
                      - id: 27be1b6a-999b-4501-a115-2ed673b6decb
                        name: Purple / Sugar
                        subtitle: null
                        image_large: null
                      variant_groups:
                      - id: 09dc5fbd-384d-46bf-b3fd-07ac96bf9ce0
                        name: Box Color
                        options:
                        - id: d25db9aa-6909-4f88-9802-68b4430c5476
                          name: Grey
                          subtitle: null
                          color: null
                          image_large: null
                        - id: 94121f3a-8797-4d54-bdd3-95f3098de2cc
                          name: Purple
                          subtitle: null
                          color: null
                          image_large: null
                      - id: f3bbc632-ca52-46f4-9675-7072140811a2
                        name: Flavor
                        options:
                        - id: 51fbe1d8-b69c-46ce-8dfd-e8c7c852354d
                          name: Chocolate Chip
                          subtitle: null
                          color: null
                          image_large: null
                        - id: d28b85fb-0f04-4261-b303-59a0020e70c9
                          name: Oatmeal
                          subtitle: null
                          color: null
                          image_large: null
                        - id: 3a28a81b-bb66-48d9-b85b-4e4048a2a61f
                          name: Sugar
                          subtitle: null
                          color: null
                          image_large: null
                      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:21:04Z'
                      status: active
                    - id: e904a2a5-badb-458b-b758-3d8ded9b34d8
                      name: Six Cookies
                      brand:
                        id: 939d0a1d-d461-4fce-b911-4fa37ddb71eb
                        name: Jeremiah Haag PhD
                        logo_image: null
                        shipping_price: 1000
                        free_shipping_minimum: null
                        brand_values:
                        - Sustainable
                      subtitle: null
                      subtitle_short: null
                      recipient_description: ''
                      variants_label: option
                      variants_num_selectable: 3
                      variants:
                      - id: 95644a01-3479-4e78-b8a4-633682aa06c0
                        name: Chocolate Chip
                        subtitle: Classic chocolate chip.
                        image_large: null
                      - id: 27d38d66-dbda-4264-9d0d-b91182fbb829
                        name: Oatmeal
                        subtitle: Delicious oatmeal.
                        image_large: null
                      - id: 5def021d-3dff-4f8e-b85f-004134ad2e91
                        name: Sugar
                        subtitle: Tasty sugar.
                        image_large: null
                      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:
                      - label: Where it's made
                        content: Made in Miami, FL
                      updated_at: '2026-07-28T20:21:04Z'
                      status: active
                    - id: fcc348de-5cd4-425a-b1e1-647b536bdfdd
                      name: Dozen Cookies
                      brand:
                        id: 939d0a1d-d461-4fce-b911-4fa37ddb71eb
                        name: Jeremiah Haag PhD
                        logo_image: null
                        shipping_price: 1000
                        free_shipping_minimum: null
                        brand_values:
                        - Sustainable
                      subtitle: null
                      subtitle_short: null
                      recipient_description: ''
                      variants_label: option
                      variants_num_selectable: 3
                      variants:
                      - id: 0f96b087-3493-43c6-a7f5-f84c49f96cfc
                        name: Chocolate Chip
                        subtitle: Classic chocolate chip.
                        image_large: null
                      - id: 4ad1165e-21cf-4876-9be4-8f092d3e15d3
                        name: Oatmeal
                        subtitle: Delicious oatmeal.
                        image_large: null
                      - id: efd918c4-aad0-498b-9fee-76f640ecbfab
                        name: Sugar
                        subtitle: Tasty sugar.
                        image_large: null
                      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:21:04Z'
                      status: active
                    list_meta:
                      total_count: 3
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
                  list_meta:
                    $ref: '#/components/schemas/ListMeta'
      operationId: getV1Products
      x-operation-id-source: derived
  /v1/products/{id}:
    get:
      summary: Retrieve a product
      tags:
      - Products
      security:
      - bearer: []
      parameters:
      - name: id
        in: path
        description: Product ID
        required: true
        schema:
          type: string
      - name: country_code
        in: query
        schema:
          type: string
          default: US
        description: Look up the product in a specific shipping country's catalog. Products are scoped to a country (default US), so a product that only ships elsewhere — e.g. an international gift card — 404s unless its country is passed here.
        required: false
      - name: use_custom_catalog
        in: query
        schema:
          type: boolean
        description: Limit to custom catalog only (for approved API partners)
        required: false
      responses:
        '200':
          description: Product retrieved
          content:
            application/json:
              examples:
                Product retrieved:
                  value:
                    id: 14eaedb5-b1cf-48c5-9408-948490dcc0ba
                    name: Six Cookies
                    brand:
                      id: 39873d74-8ed8-47a3-a5c3-65b7b916b36b
                      name: Ruby Emmerich
                      logo_image: null
                      shipping_price: 1000
                      free_shipping_minimum: null
                      brand_values: []
                    subtitle: null
                    subtitle_short: null
                    recipient_description: ''
                    variants_label: option
                    variants_num_selectable: 3
                    variants:
                    - id: 83827f45-7be0-4b79-861f-d3cfd927aa52
                      name: Chocolate Chip
                      subtitle: Classic chocolate chip.
                      image_large: null
                    - id: bc07e5e4-c5ed-4318-b1f4-d2d979a2c4a1
                      name: Oatmeal
                      subtitle: Delicious oatmeal.
                      image_large: null
                    - id: 1753dd70-8070-48f5-8044-b8fa660fe869
                      name: Sugar
                      subtitle: Tasty sugar.
                      image_large: null
                    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:21:05Z'
                    status: active
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          description: Product not found
          content:
            application/json:
              examples:
                Product not found:
                  value:
                    error: Product not found
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getV1ProductsById
      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
    ListMeta:
      type: object
      properties:
        total_count:
          type: integer
          description: The total number of items in this list.
    ProductImage:
      type: object
      properties:
        id:
          type: string
          format: uuid
        image_large:
          $ref: '#/components/schemas/Image'
      required:
      - id
      - image_large
    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
    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
    BrandSetImage:
      type: object
      properties:
        id:
          type: string
          format: uuid
        image_large:
          $ref: '#/components/schemas/Image'
      required:
      - id
      - image_large
    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
    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
          - '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)