Goody Orders API
The Orders API from Goody — 4 operation(s) for orders.
OpenAPI Specification
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.