openapi: 3.0.1
info:
  title: Goody Brands Orders 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: Orders
paths:
  /v1/orders/{id}/cancel:
    parameters:
    - name: id
      in: path
      description: id
      required: true
      schema:
        type: string
    post:
      summary: Cancel an order
      tags:
      - Orders
      security:
      - bearer: []
      responses:
        '200':
          description: Order canceled
          content:
            application/json:
              examples:
                Order canceled:
                  value:
                    id: 04505127-3b1c-4488-b5f4-1c85e6befe53
                    status: failed
                    individual_gift_link: https://gifts.ongoody.com/gift/GIOORGY1KFPCECWSRIPGV5BY
                    recipient_first_name: Michael
                    recipient_last_name: Franci
                    recipient_email: michael@ongoody.com
                    card_id: 1030e98b-3d80-4aa1-a348-069c2037dd70
                    message: Test Message
                    thank_you_note: null
                    view_count_recipient: 0
                    is_swapped: false
                    order_batch_id: 4f57be1a-5ac1-4f0b-a830-bda27c8e063c
                    expires_at: null
                    cart:
                      id: 59b0d301-27c7-453e-95e9-a82dc0f8af0b
                      items:
                      - id: d8d7bfc9-8496-4b77-8e9c-d084cef94cd7
                        quantity: 1
                        product:
                          id: f2a5701d-dc75-455b-b932-8d01310b2153
                          name: Cookies
                          brand:
                            id: 064854e3-a0c5-49b4-8406-5e6e86834702
                            name: Cookie Company
                    cart_selections:
                    - id: beb8b93e-7224-44b2-96f2-a9e9d46dc0b0
                      cart_item_id: bb9735b7-ec0b-4b92-8011-1bac5c3ed5fd
                      quantity_index: 0
                      variants: []
                    shipments: []
                    amounts:
                      amount_product: 2000
                      amount_shipping: 500
                      amount_processing_fee: 0
                      amount_pre_tax_total: 2500
                      amount_tax: null
                      amount_total: null
                      amount_global_relay_cost: null
                    sender:
                      first_name: Test
                      last_name: User
                      email: 15550002890@test.ongoody.com
                    workspace_id: 3e276f0f-8863-445e-9ed2-0a3b1abdeb45
                    workspace_name: Test Team
                    original_cart: null
                    original_amounts: null
                    reference_id: CV44HAL5HRQ10SHWDBZ2IS9T
                    payment_link: null
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: Order not found
          content:
            application/json:
              examples:
                Order not found:
                  value:
                    error: Order not found
              schema:
                $ref: '#/components/schemas/Error'
  /v1/orders:
    get:
      summary: List orders
      tags:
      - Orders
      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: created_at[after]
        in: query
        schema:
          type: string
          format: date-time
          description: ISO 8601
          nullable: true
        description: Filter orders created at or after this timestamp (ISO 8601, UTC unless otherwise specified in timestamp)
        required: false
      - name: created_at[before]
        in: query
        schema:
          type: string
          format: date-time
          description: ISO 8601
          nullable: true
        description: Filter orders created at or before this timestamp (ISO 8601, UTC unless otherwise specified in timestamp)
        required: false
      responses:
        '200':
          description: Orders retrieved
          content:
            application/json:
              examples:
                Orders retrieved:
                  value:
                    data:
                    - id: 7a449dc9-8a31-4a90-abbd-19143552aa52
                      status: created
                      individual_gift_link: https://gifts.ongoody.com/gift/1FE9DWTJC4T85G8QN5SDB3LH
                      recipient_first_name: Michael
                      recipient_last_name: Franci
                      recipient_email: michael@ongoody.com
                      card_id: 2d738268-5496-43e1-ad4d-cca8b7810fc3
                      message: Test Message
                      thank_you_note: null
                      view_count_recipient: 0
                      is_swapped: false
                      order_batch_id: 9e3ede84-8280-479f-ac9b-9007bb45a23c
                      expires_at: null
                      cart:
                        id: 987e757c-8faa-42b2-8845-3f98794a7b5b
                        items:
                        - id: fdd90649-ed42-461f-8672-f9cc3f051bc9
                          quantity: 1
                          product:
                            id: 31de335c-3a0e-4dcf-807f-9f32e7ccc108
                            name: Cookies
                            brand:
                              id: 46ab78f4-729a-4b31-9cbc-32266daedd04
                              name: Cookie Company
                      shipments: []
                      amounts:
                        amount_product: 2000
                        amount_shipping: 500
                        amount_processing_fee: 0
                        amount_pre_tax_total: 2500
                        amount_tax: null
                        amount_total: null
                        amount_global_relay_cost: null
                      sender:
                        first_name: Test
                        last_name: User
                        email: 15552492933@test.ongoody.com
                      workspace_id: 01e3dd01-1967-4069-9edc-d6755de1b7f3
                      workspace_name: Test Team
                      original_cart: null
                      original_amounts: null
                      reference_id: BTGGI5EEFNIHTGXXEJ16CDCJ
                      payment_link: null
                    - id: d248f1c5-44e8-432b-8941-5a93f6eec845
                      status: created
                      individual_gift_link: https://gifts.ongoody.com/gift/JKVE5ZLZADLVN2GRUJUSARIW
                      recipient_first_name: Alena
                      recipient_last_name: Kenter
                      recipient_email: alena@ongoody.com
                      card_id: 2d738268-5496-43e1-ad4d-cca8b7810fc3
                      message: Test Message
                      thank_you_note: null
                      view_count_recipient: 0
                      is_swapped: false
                      order_batch_id: 9e3ede84-8280-479f-ac9b-9007bb45a23c
                      expires_at: null
                      cart:
                        id: 987e757c-8faa-42b2-8845-3f98794a7b5b
                        items:
                        - id: fdd90649-ed42-461f-8672-f9cc3f051bc9
                          quantity: 1
                          product:
                            id: 31de335c-3a0e-4dcf-807f-9f32e7ccc108
                            name: Cookies
                            brand:
                              id: 46ab78f4-729a-4b31-9cbc-32266daedd04
                              name: Cookie Company
                      shipments: []
                      amounts:
                        amount_product: 2000
                        amount_shipping: 500
                        amount_processing_fee: 0
                        amount_pre_tax_total: 2500
                        amount_tax: null
                        amount_total: null
                        amount_global_relay_cost: null
                      sender:
                        first_name: Test
                        last_name: User
                        email: 15552492933@test.ongoody.com
                      workspace_id: 01e3dd01-1967-4069-9edc-d6755de1b7f3
                      workspace_name: Test Team
                      original_cart: null
                      original_amounts: null
                      reference_id: 4XLDWNOT1MFZROIUSJ8K84Y8
                      payment_link: null
                    list_meta:
                      total_count: 2
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  list_meta:
                    $ref: '#/components/schemas/ListMeta'
  /v1/orders/{id}:
    parameters:
    - name: id
      in: path
      description: id
      required: true
      schema:
        type: string
    get:
      summary: Retrieve an order
      tags:
      - Orders
      security:
      - bearer: []
      responses:
        '200':
          description: Order retrieved
          content:
            application/json:
              examples:
                Order retrieved:
                  value:
                    id: 2bcc47f6-bea1-4ac6-a103-0c686b075c21
                    status: created
                    individual_gift_link: https://gifts.ongoody.com/gift/WXN0IOGPRNLMHWT950JGP9SC
                    recipient_first_name: Alena
                    recipient_last_name: Kenter
                    recipient_email: alena@ongoody.com
                    card_id: d39f10a0-1c28-4ee7-93f6-739ba625e3a2
                    message: Test Message
                    thank_you_note: null
                    view_count_recipient: 0
                    is_swapped: false
                    order_batch_id: fc6fb6d4-2917-48f3-9ef3-3c0fad91bb5b
                    expires_at: null
                    cart:
                      id: 1a3f74fe-a2e4-4327-933d-f238d81c467c
                      items:
                      - id: fd780305-dfa9-402e-b1af-1a1592ab3030
                        quantity: 1
                        product:
                          id: afe33526-cdc6-462d-9353-ddcf9a1f8e6e
                          name: Cookies
                          brand:
                            id: 8f93b70d-fb3a-44e3-9f95-6e698024017c
                            name: Cookie Company
                    cart_selections:
                    - id: 7fc69885-8518-4fe1-bda6-9863d92c334b
                      cart_item_id: 69310000-b564-404f-b780-2d1ab7841952
                      quantity_index: 0
                      variants: []
                    shipments: []
                    amounts:
                      amount_product: 2000
                      amount_shipping: 500
                      amount_processing_fee: 0
                      amount_pre_tax_total: 2500
                      amount_tax: null
                      amount_total: null
                      amount_global_relay_cost: null
                    sender:
                      first_name: Test
                      last_name: User
                      email: 15558314938@test.ongoody.com
                    workspace_id: ca507888-8d3c-4608-aed9-8cb07034cade
                    workspace_name: Test Team
                    original_cart: null
                    original_amounts: null
                    reference_id: QGIMV1BPGSJ3DA58T4MACS03
                    event_times:
                      created_at: '2026-06-03T12:25:15Z'
                      notified_at: null
                      opened_at: null
                      accepted_at: null
                      thank_you_added_at: null
                      pending_payment_at: null
                      paid_at: null
                      shipped_at: null
                      delivered_at: null
                    payment_link: null
                Order with cart selections:
                  value:
                    id: 95c9fe72-43e7-4e44-bc5b-6f212679e46e
                    status: created
                    individual_gift_link: https://gifts.ongoody.com/gift/QMNNZXOJHXRCFISDUGI3SH53
                    recipient_first_name: Alena
                    recipient_last_name: Kenter
                    recipient_email: alena@ongoody.com
                    card_id: ef0f8cbc-9c70-41bc-9c28-8bc7ac73baa7
                    message: Test Message
                    thank_you_note: null
                    view_count_recipient: 0
                    is_swapped: false
                    order_batch_id: ee8f2bb2-71e0-40a0-88df-fda475db9922
                    expires_at: null
                    cart:
                      id: 18fd065d-9625-435e-889f-c1b78d302bfb
                      items:
                      - id: f37a5857-cb81-4c12-9e29-ccce23bc760d
                        quantity: 1
                        product:
                          id: 5475f9cf-50a8-45f4-8df1-05c6485abcc3
                          name: Cookies
                          brand:
                            id: fd608245-aae8-48e7-9bc2-4a23afdafcfa
                            name: Cookie Company
                    cart_selections:
                    - id: df58d307-9653-4dac-bef0-e019df472cda
                      cart_item_id: f37a5857-cb81-4c12-9e29-ccce23bc760d
                      quantity_index: 0
                      variants:
                      - Black
                    shipments: []
                    amounts:
                      amount_product: 2000
                      amount_shipping: 500
                      amount_processing_fee: 0
                      amount_pre_tax_total: 2500
                      amount_tax: null
                      amount_total: null
                      amount_global_relay_cost: null
                    sender:
                      first_name: Test
                      last_name: User
                      email: 15552247945@test.ongoody.com
                    workspace_id: f6ef00ac-44fd-450a-9d43-6d6532305a9e
                    workspace_name: Test Team
                    original_cart: null
                    original_amounts: null
                    reference_id: PNC93R4LTVFFLMDHKKRDZDAR
                    event_times:
                      created_at: '2026-06-03T12:25:15Z'
                      notified_at: null
                      opened_at: null
                      accepted_at: null
                      thank_you_added_at: null
                      pending_payment_at: null
                      paid_at: null
                      shipped_at: null
                      delivered_at: null
                    payment_link: null
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: Order not found
          content:
            application/json:
              examples:
                Order not found:
                  value:
                    error: Order not found
              schema:
                $ref: '#/components/schemas/Error'
  /v1/orders/{id}/update_expiration:
    parameters:
    - name: id
      in: path
      description: id
      required: true
      schema:
        type: string
    post:
      summary: Update expiration for an order
      tags:
      - Orders
      security:
      - bearer: []
      parameters: []
      responses:
        '200':
          description: Expiration updated
          content:
            application/json:
              examples:
                Expiration updated:
                  value:
                    id: e87c260d-011c-4b0e-9878-a61e4cb05797
                    status: created
                    individual_gift_link: https://gifts.ongoody.com/gift/NVFEBIPXKRHEQSMLTOS1YWQ2
                    recipient_first_name: Alena
                    recipient_last_name: Kenter
                    recipient_email: alena@ongoody.com
                    card_id: c9095d35-d256-4fcd-92e9-7593290a0030
                    message: Test Message
                    thank_you_note: null
                    view_count_recipient: 0
                    is_swapped: false
                    order_batch_id: 698a9466-f372-4317-ace4-bb21b2ac8a85
                    expires_at: '2022-02-01T00:00:00Z'
                    cart:
                      id: a6821fed-292b-42a2-b32e-8e87d7832c87
                      items:
                      - id: 1c110452-f8e9-441d-83e8-48c003e1f85a
                        quantity: 1
                        product:
                          id: 12ad03c2-640c-425a-9721-e91d2871b5aa
                          name: Cookies
                          brand:
                            id: b8fed488-5934-42fc-a0dd-76af3355bb35
                            name: Cookie Company
                    shipments: []
                    amounts:
                      amount_product: 2000
                      amount_shipping: 500
                      amount_processing_fee: 0
                      amount_pre_tax_total: 2500
                      amount_tax: null
                      amount_total: null
                      amount_global_relay_cost: null
                    sender:
                      first_name: Test
                      last_name: User
                      email: 15558690162@test.ongoody.com
                    workspace_id: 8412c9de-f6c7-4780-830f-7e3573078b3c
                    workspace_name: Test Team
                    original_cart: null
                    original_amounts: null
                    reference_id: A7T4NOKKSHXYVTGPSFDYFVZW
                    payment_link: null
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: Order not found
          content:
            application/json:
              examples:
                Order not found:
                  value:
                    error: Order not found
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                expiration:
                  type: string
                  format: date-time
                  example: 2022-02-01T00:00:00+0000
                  description: New expiration date in ISO 8601 format
components:
  schemas:
    Order:
      type: object
      description: An individual order contains the gift link to be sent to the recipient (if applicable) and other information about the order.
      properties:
        id:
          type: string
          format: uuid
        recipient_first_name:
          type: string
        recipient_last_name:
          type: string
          nullable: true
        recipient_email:
          type: string
          nullable: true
        status:
          $ref: '#/components/schemas/OrderStatus'
        individual_gift_link:
          type: string
          description: This gift link can be sent to the recipient or shared with the sender. For privacy reasons, this gift link does not display tracking information. A separate link, the recipient link, is sent directly to the recipient after they accept their gift, which does contain tracking information.
        cart:
          $ref: '#/components/schemas/Cart'
          description: The cart currently on this order. If the order is a gift that was swapped, `cart` displays the most recent products selected (i.e. post-swap).
        cart_selections:
          type: array
          items:
            $ref: '#/components/schemas/CartSelection'
          description: Product variant selections for each cart product. Only for commerce app orders.
          nullable: true
        shipments:
          type: array
          items:
            $ref: '#/components/schemas/Shipment'
          description: A list of the shipments for the order.
        workspace_id:
          type: string
          format: uuid
          nullable: true
          description: Organizations are sub-divided into workspaces. Orders are contained in workspaces, identified by this ID.
        workspace_name:
          type: string
          nullable: true
        expires_at:
          type: string
          format: date-time
          description: For gifts, the date and time the gift is set to expire.
          nullable: true
        card_id:
          type: string
          format: uuid
          nullable: true
          description: The digital greeting card on this gift.
        message:
          type: string
          nullable: true
          description: The message in this gift, provided by the sender.
        thank_you_note:
          type: string
          nullable: true
          description: A thank you note sent by the recipient.
        view_count_recipient:
          type: integer
          description: The number of times the recipient viewed the gift.
        is_swapped:
          type: boolean
          description: If this gift was swapped by the recipient. Swapping allows a recipient to select another product or products, which replaces the `cart`. The original products are saved to `original_cart`.
        order_batch_id:
          type: string
          format: uuid
          description: On Goody for Business, all orders are attached to a order batch, which is a collection of one or more orders.
        amounts:
          type: object
          description: Costs in USD cents (i.e. $1.00 = 100). If the order was swapped, `amounts` displays the most recent amounts (i.e. post-swap).
          properties:
            amount_product:
              type: integer
              description: Total cost of the products in this order.
            amount_shipping:
              type: integer
              description: Total cost of shipping for this order.
            amount_processing_fee:
              type: integer
              nullable: true
              description: Total cost of processing fees for this order.
            amount_credit_applied:
              type: integer
              nullable: true
              description: Total amount of credit applied to this order.
            amount_pre_tax_total:
              type: integer
              description: Total cost of the products, shipping, and processing fees in this order.
            amount_tax:
              type: integer
              nullable: true
              description: Total tax for this order.
            amount_total:
              type: integer
              nullable: true
              description: Total cost of the products, shipping, processing fees, tax, and global shipping costs in this order.
            amount_global_relay_cost:
              type: integer
              nullable: true
              description: Total cost of global shipping for this order through the Global Relay service.
          required:
          - amount_product
          - amount_shipping
          - amount_pre_tax_total
        event_times:
          type: object
          description: Only provided when calling the /orders/:id endpoint.
          properties:
            created_at:
              type: string
              format: date-time
              description: ISO 8601
            notified_at:
              type: string
              format: date-time
              description: When the recipient was notified of the order.
              nullable: true
            opened_at:
              type: string
              format: date-time
              description: For gifts, when the recipient opened the order.
              nullable: true
            accepted_at:
              type: string
              format: date-time
              description: For gifts, when the recipient accepted the order.
              nullable: true
            pending_payment_at:
              type: string
              format: date-time
              description: When the order entered pending payment status.
              nullable: true
            paid_at:
              type: string
              format: date-time
              description: When the order was paid for.
              nullable: true
            shipped_at:
              type: string
              format: date-time
              description: When the order was first shipped. If there are multiple shipments, this is when the first shipment shipped.
              nullable: true
            delivered_at:
              type: string
              format: date-time
              description: When the order was delivered. If there are multiple shipments, this is when all shipments were delivered.
              nullable: true
          required:
          - created_at
          nullable: true
        original_cart:
          $ref: '#/components/schemas/Cart'
          description: If this order is a gift that was swapped, this displays the original cart that was sent to the recipient.
          nullable: true
        original_amounts:
          type: object
          description: If this order is a gift that was swapped, this displays the original amounts of the cart that was sent to the recipient.
          properties:
            original_amount_product:
              type: integer
              nullable: true
            original_amount_shipping:
              type: integer
              nullable: true
            original_amount_credit_applied:
              type: integer
              nullable: true
            original_amount_pre_tax_total:
              type: integer
              nullable: true
          nullable: true
        sender:
          $ref: '#/components/schemas/Sender'
          description: The Goody user who sent this order.
        payment_link:
          type: string
          nullable: true
          description: For commerce apps using Hosted Payment, the payment link for the gift with the credit card entry form. Available when the gift is in `pending_payment` status (after it has been accepted).
        reference_id:
          type: string
          description: The reference ID displayed on receipts and other locations as the ID for this order.
      required:
      - id
      - recipient_first_name
      - status
      - individual_gift_link
      - cart
      - shipments
      - amounts
      - sender
      - reference_id
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    Shipment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - pending
          - tracking
          - shipped
          - delivered
          - delivered_override
          - failed
          - failed_unset_tracking
          - failed_with_reship
        brand_name:
          type: string
          description: The name of the brand that this shipment is from.
        tracking_carrier:
          type: string
          nullable: true
          description: The carrier for this shipment, e.g. UPS.
        tracking_number:
          type: string
          nullable: true
          description: Only for approved distribution partners.
        tracking_url:
          type: string
          nullable: true
          description: Only for approved distribution partners.
        shipped_at:
          type: string
          format: date-time
          description: ISO 8601
          nullable: true
        delivered_at:
          type: string
          format: date-time
          description: ISO 8601
          nullable: true
        delivery_eta:
          type: string
          format: date-time
          description: The estimated delivery time of this shipment.
          nullable: true
      required:
      - id
      - status
      - brand_name
    OrderStatus:
      type: string
      enum:
      - created
      - notified
      - opened
      - accepted
      - pending_payment
      - paid
      - ordered
      - shipped
      - delivered
      - failed
      - canceled
    Sender:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
      required:
      - first_name
      - last_name
      - email
    ListMeta:
      type: object
      properties:
        total_count:
          type: integer
          description: The total number of items in this list.
    Cart:
      type: object
      properties:
        id:
          type: string
          format: uuid
        items:
          type: array
          items:
            $ref: '#/components/schemas/CartItem'
    CartItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
        product:
          type: object
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
            brand:
              type: object
              description: The brand that this product is from.
              properties:
                id:
                  type: string
                  format: uuid
                name:
                  type: string
              required:
              - id
              - name
          required:
          - id
          - name
          - brand
        quantity:
          type: integer
      required:
      - id
      - product
      - quantity
    CartSelection:
      type: object
      description: Product variant selections for a specific gift cart product.
      properties:
        id:
          type: string
          format: uuid
        cart_item_id:
          type: string
          format: uuid
          description: The cart item ID this selection belongs to. Match this with cart.items[].id.
        quantity_index:
          type: integer
          description: The index of this selection within multiple quantities of the same product. If a given cart product has multiple quantities, this will be 0 for the first unit, 1 for the second unit, etc.
        variants:
          type: array
          items:
            type: string
          description: The selected variants for this product selection and quantity index.
      required:
      - id
      - cart_item_id
      - quantity_index
      - variants
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: Your Goody API key.