# List all active cards GET /v1/cards # Calculate the price for an order batch POST /v1/order_batches/price You can calculate the total price for an order batch before you create it, given a cart, recipients, and send method. To use a specific address, pass the `direct_send` send method. # Create an order batch POST /v1/order_batches For a guide on how to create an order batch, see the Getting Started guide for the [Automation API Getting Started](/automation-api/create-an-order) guide or the [Commerce API Getting Started](/commerce-api/create-an-order) guide. ### Order batches with 10 or fewer recipients Order batches with 10 or fewer recipients are created synchronously, and the returned `status` field will be `completed`. The orders and order links are available immediately inside the `orders_preview` field (which returns the first 10 orders). ### Order batches with more than 10 recipients Order batches with more than 10 recipients are created asynchronously, and the order batch will have a `status` of `pending`. The orders and gift links won't be available until the order batch is finished processing synchronously. You can check the status of the order batch by calling the [`/order_batches/:id`](retrieve-an-order-batch) endpoint, or by receiving a webhook notification on the [`order_batch.completed`](/webhooks/events/order_batch.completed) event. Once an order batch is created, you can access all of the orders by calling the `/order_batches/:id/orders` endpoint, where you can paginate through the list of orders. If your use case always sends 10 or fewer orders at a time, you can just use the `orders_preview` field on the order batch which gives you the first 10 orders. # List all order batches GET /v1/order_batches # Retrieve an order batch GET /v1/order_batches/{id} # Retrieve orders for an order batch GET /v1/order_batches/{id}/orders # Retrieve recipients for an order batch GET /v1/order_batches/{id}/recipients # Cancel an order POST /v1/orders/{id}/cancel # List all orders GET /v1/orders # Retrieve an order GET /v1/orders/{id} # Update expiration for an order POST /v1/orders/{id}/update_expiration # List all payment methods GET /v1/payment_methods # List all active products GET /v1/products # Retrieve a product GET /v1/products/{id} # Retrieve current user GET /v1/me # Brand # Cart # CartInput # CartItem # CartItemInput # Error # Image # ListMeta # MailingAddress # Me # Order # OrderBatch # OrderBatchInput # OrderBatchRecipient # OrderBatchSendMethod # OrderBatchSendStatus # OrderStatus # Product # ProductImage # ProductVariant # RecipientInput # Sender # Shipment # List all workspaces GET /v1/workspaces # Automation API: Access the product catalog You don't need to access the product catalog to specify what product you want to send. You can find the product ID by enabling [Developer Mode](/introduction/developer-mode) on Goody's website, or you can use the product's URL in the create order batch payload. However, you can still access the product catalog if your use case can benefit from it. To access the product catalog, make a request (using your API key) to: ``` GET https://api.sandbox.ongoody.com/v1/products Authorization: Bearer YOUR_GOODY_API_KEY ``` This endpoint returns the products that are available to send. The list of products can change as products are added and removed. The product object includes the brand name, price, brand shipping price, copy like subtitles, variant information, and product imagery. You can paginate the product catalog by passing the `?page=` query parameter (the first page is `1`) and the `?per_page` query parameter (maximum `100`) to paginate through the list. An example response might look like: ```json { "data": [ { "id": "5821e50e-6a56-4144-bca2-3f41fbd699c0", "name": "Dozen Cookies", "brand": { "id": "30e28df2-730e-4763-81bc-d528f0ac6a2a", "name": "Cookie Company", "shipping_price": 1000 }, "subtitle": null, "subtitle_short": null, "recipient_description": "", "variants_label": "Flavor", "variants_num_selectable": 1, "variants": [ { "id": "5eab976a-614c-41cf-a46f-8eca96748fbf", "name": "Chocolate Chip", "subtitle": "Classic chocolate chip.", "image_large": { "url": "https://assets.ongoody.com/image.png", "width": 1000, "height": 500 } }, { "id": "95592e6d-0bd3-49e9-ad2b-0112232e31d6", "name": "Oatmeal", "subtitle": "Delicious oatmeal.", "image_large": { "url": "https://assets.ongoody.com/image.png", "width": 1000, "height": 500 } }, { "id": "fe10b3ac-02b4-4b4e-b5cc-d16303fb1091", "name": "Sugar", "subtitle": "Tasty sugar.", "image_large": { "url": "https://assets.ongoody.com/image.png", "width": 1000, "height": 500 } } ], "images": [ { "id": "4fdc04a5-35e8-4789-84b9-c84259918f36", "image_large": { "url": "https://assets.ongoody.com/image.png", "width": 1000, "height": 500 } } ], "price": 1000, "price_is_variable": false, "restricted_states": [] } ], "list_meta": { "total_count": 1 } } ``` For more information, including the schema of the Product object, check out the [API reference for the products endpoint](/api-reference/products/list-all-active-products). # Automation API: Authentication Production and Sandbox accounts are separate, and you have different API keys for each environment for isolation. ## Create a Goody for Business account To sign up for a Goody for Business account in production or sandbox, go to the corresponding link: | Environment | API Keys Link | | -------------- | ------------------------------------------------------------------------------------------ | | **Production** | [https://www.ongoody.com/business/signup](https://www.ongoody.com/business/signup) | | **Sandbox** | [https://sandbox.ongoody.com/business/signup](https://sandbox.ongoody.com/business/signup) | ## Create an API Key Once you're signed up, to create an API key, go to the top-right account menu, and click **Account**, and then click the **API Keys** sub-menu. Or, use the links below. | Environment | API Keys Link | | -------------- | ------------------------------------------------------------------------------------------------------ | | **Production** | [https://www.ongoody.com/plus/account/api-keys](https://www.ongoody.com/plus/account/api-keys) | | **Sandbox** | [https://sandbox.ongoody.com/plus/account/api-keys](https://sandbox.ongoody.com/plus/account/api-keys) | ## Base URL The base URL of the API depends on the environment you're using: | Environment | API Keys Link | | -------------- | ------------------------------------------------------------------ | | **Production** | [https://api.ongoody.com](https://api.ongoody.com) | | **Sandbox** | [https://api.sandbox.ongoody.com](https://api.sandbox.ongoody.com) | ## Authentication header This API uses bearer authentication. Send your API key in the `Authorization` HTTP header preceded by `Bearer` : ``` Authorization: Bearer YOUR_GOODY_API_KEY ``` API keys are scoped to users, and any orders created with your API key show up in your Goody for Business account like orders created from the website. You can track them on the Track page. ## Calling `/me` To check that you're authenticated, you can send a request to the `/me` endpoint: ``` GET https://api.sandbox.ongoody.com/v1/me Authorization: Bearer YOUR_GOODY_API_KEY ``` And it should respond with: ```json { "email": "example-email@ongoody.com" } ``` # Automation API: Create an order ## Send a gift One of the ways you can use the Automation API is to send a gift. When you send a gift, you can create an order without an address, and you'll get a gift link that you can send to the recipient. The recipient can then enter their own address and accept the gift. To send a gift, you'll want to create what we call an **order batch**. Since Goody lets you send gifts to multiple recipients at once, the "container" for all gifts is an order batch. When you create an order batch, you provide a list of recipients. Each recipient in the gift batch will have an order created for them. If you're sending a single gift at a time, you'll also be creating an order batch – just with one recipient. Think of it as sending an email: whether you're sending an email to one recipient or multiple, you're still composing the same email. The endpoint to create a gift batch is [POST /v1/order\_batches](/api-reference/order-batches/create-an-order-batch). Let's take a look at an example payload for creating an order batch: ```json { "from_name": "John", "send_method": "link_multiple_custom_list", "recipients": [ { "first_name": "Alena", "last_name": "Kenter", "email": "alena@ongoody.com" } ], "cart": { "items": [ { "product_id": "9abf2d67-e4f3-4d43-9142-4a1f0d10aaa0", "quantity": 1 } ] }, "card_id": "ff957080-192d-4032-b4c5-fbb057141c4b", "message": "Thank you!" } ``` These fields are required in each order batch: | Field | Meaning | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `from_name` | **Who is the gift from?** This name is the "from" when the gift is displayed. | | `send_method` | **How do you want to send this gift?** Do you want Goody to send a gift notification email, or just get a link to send on your own? In this case, we're using `link_multiple_custom_list`, which means to get links only without sending an email. For more information, see the Send methods documentation page TK. | | `recipients` | **Who is this gift going to?** If you only have one gift recipient, this array will just have one item. Only `first_name` is required (unless if you want us to send a gift email, in which case you'll also need to provide `email`). | | `cart` | **What products do you want to send in your gift?** Each product you send is an item in the `cart.items` array. You can find Product IDs from the product catalog, or by using Developer Mode on the Goody website (TK). | These fields are optional, but recommended: | Field | Meaning | | --------- | --------------------------------------------- | | `card_id` | (optional) The ID of a digital greeting card. | | `message` | (optional) A message to add to your gift. | ### Create order batch response The response looks like: ```json { "id": "f0903768-609c-4851-bc9a-c17ea245e120", "send_status": "complete", "from_name": "John", "message": "Thank you!", "orders_count": 1, "orders_preview": [ { "id": "a74adf4b-1837-43f5-8e51-f74803cd8832", "status": "created", "recipient_first_name": "Alena", "recipient_last_name": "Kenter", "recipient_email": "alena@ongoody.com", "individual_gift_link": "https://gifts.ongoody.com/gift/gHBMKuXkiVgAFDyXx00h4XGs", "card_id": "ff957080-192d-4032-b4c5-fbb057141c4b", "message": "Thank you!", "thank_you_note": null, "view_count_recipient": 0, "is_swapped": false, "order_batch_id": "f0903768-609c-4851-bc9a-c17ea245e120", "cart": { "id": "fad70b58-896e-4e11-b80b-d807f57e5e3d", "items": [ { "id": "0bc34fa6-d036-4300-a743-dec8eda7f2bd", "quantity": 1, "product": { "id": "9abf2d67-e4f3-4d43-9142-4a1f0d10aaa0", "name": "Cookies", "brand": { "id": "d8782dff-10b2-49ca-87ed-ed6c9d34e4bd", "name": "Cookie Company" } } } ] }, "shipments": [], "amounts": { "amount_product": 1000, "amount_shipping": 1000, "amount_processing_fee": 100, "amount_pre_tax_total": 2100, "amount_tax": null, "amount_total": null, "amount_global_relay_cost": null }, "sender": { "first_name": "Test", "last_name": "User", "email": "15557426864@test.ongoody.com" }, "workspace_id": "b99bf758-104f-4570-a3a9-bc59e64646b1", "workspace_name": "Test Team", "original_cart": null, "original_amounts": null, "reference_id": "5NRQ9IKCVECOHFCUOZWJHTWW" } ], "recipients_count": 1, "recipients_preview": [ { "first_name": "Alena", "last_name": "Kenter", "email": "alena@ongoody.com" } ], "cart": { "id": "fad70b58-896e-4e11-b80b-d807f57e5e3d", "items": [ { "id": "0bc34fa6-d036-4300-a743-dec8eda7f2bd", "quantity": 1, "product": { "id": "9abf2d67-e4f3-4d43-9142-4a1f0d10aaa0", "name": "Cookies", "brand": { "id": "d8782dff-10b2-49ca-87ed-ed6c9d34e4bd", "name": "Cookie Company" } } } ] }, "is_scheduled_send": false, "scheduled_send_on": null, "expires_at": null, "send_method": "link_multiple_custom_list", "batch_name": "Alena Kenter", "card_id": "ff957080-192d-4032-b4c5-fbb057141c4b", "sender": { "first_name": "Test", "last_name": "User", "email": "15557426864@test.ongoody.com" }, "workspace_id": "b99bf758-104f-4570-a3a9-bc59e64646b1", "workspace_name": "Test Team", "reference_id": "XNYLJMW5JIFOFRM0PQIPNA56" } ``` * **If you send an order batch with 10 or fewer recipients**, orders are processed right away, and you'll see that that `send_status` is `complete` and you'll receive the list of orders back in the `orders_preview` object. * **If you send an order batch with more than 10 recipients**, creating orders happens asynchronously in the background, and you'll see that `send_status` is `pending`. You can hit the [`/order_batches/:id`](/api-reference/order-batches/retrieve-an-order-batch) endpoint to check the `send_status` for complete, or listen for the `order_batch.completed` webhook. * The `orders_preview` endpoint only contains the first 10 orders. If you have more orders, you can paginate through all the orders using the [`/order_batches/:id/orders`](/api-reference/order-batches/retrieve-orders-for-an-order-batch) endpoint. * **If you schedule an order batch for the future** using the `scheduled_send_on` parameter, the `send_status` will be `pending`, and `orders_preview` will be empty, until the scheduled send time, at which point the orders are created. Similarly to above, you can listen for the `order_batch.completed` webhook. You can check the send\_status field to determine if your order batch is being asynchronously processed or is scheduled for the future (`send_status == pending`) or orders are ready (`send_status == complete`). ### The `orders_preview` field The most important thing in the response is the order object. The `orders_preview` field displays the first 10 orders in your order batch. To determine the number of orders in the order batch, you can use the `orders_count` field. ```json "orders_count": 1, "orders_preview": [ { "id": "a74adf4b-1837-43f5-8e51-f74803cd8832", "status": "created", "recipient_first_name": "Alena", "recipient_last_name": "Kenter", "recipient_email": "alena@ongoody.com", "individual_order_link": "https://gifts.ongoody.com/gift/gHBMKuXkiVgAFDyXx00h4XGs", "card_id": "ff957080-192d-4032-b4c5-fbb057141c4b", "message": "Thank you!", "thank_you_note": null, "view_count_recipient": 0, "is_swapped": false, "order_batch_id": "f0903768-609c-4851-bc9a-c17ea245e120", "cart": { ... }, "shipments": [], "amounts": { "amount_product": 1000, "amount_shipping": 1000, "amount_processing_fee": 100, "amount_pre_tax_total": 2100, "amount_tax": null, "amount_total": null, "amount_global_relay_cost": null }, "sender": { "first_name": "Test", "last_name": "User", "email": "15557426864@test.ongoody.com" }, "workspace_id": "b99bf758-104f-4570-a3a9-bc59e64646b1", "workspace_name": "Test Team", "original_cart": null, "original_amounts": null, "reference_id": "5NRQ9IKCVECOHFCUOZWJHTWW" }, ] ``` If you always send single orders or fewer than 10 orders at once, great! You can use this array without having to make another request. But if you send more than 10 orders at once, you can also hit the `/order_batches/:id/orders` endpoint to paginate through the rest of your orders. In the order object, there are a few fields to point out: * `individual_gift_link` — This is the individual gift link for that recipient, which when opened goes directly to their gift. You can send this in an email or somewhere else so they can access their gift. * `status` — This status is for the individual order itself. The list of order statuses can be viewed on the [order lifecycle guide](/introduction/order-lifecycle). You can set up webhooks to get notified on changes to the status. * `amounts` — Contains the costs for this order, in cents. Congratulations – you've sent a gift! For more information on the order batch send endpoint, [visit the doc](/api-reference). ## Next steps Now that you've sent your gift, you can now open the gift link and accept the gift to see what the experience looks like. # Goody Automation API Goody for Business customers can use the Automation API to automate their gifting and sending. With the Automation API, you can programmatically create one-to-one or one-to-many gifts, retrieve information about orders, and get real-time webhook notifications on order events. Some things you can build with the Automation API: * **Trigger sending gifts on events in your CRM, HRIS, or another application.** Send a customer gift for client anniversaries, deals closed, and more. * **Send Goody order information to other applications.** Trigger Slack messages on gift accepts, add tasks in your CRM when gifts are delivered, save order totals to a spreadsheet, and more. ## Getting started In this guide, we'll walk through how to: 1. Set up an account on our sandbox environment 2. Obtain an API key 3. Send a gift 4. Set up webhooks for order events. Let's start with setting up an account and authentication. # Automation API: Retrieve order status ## Get order In most cases, you'll want to get information about an individual order. You can retrieve an order by calling the [GET /orders/:id](/api-reference/orders/retrieve-an-order) endpoint. This will return all information about the order, in particular its status, such as notified, opened, shipped, delivered, etc. For more information on all of the available order statuses, visit the Order Lifecycle documentation page. For more information about the other fields in the Order object, refer to the [Order schema](/api-reference/schemas/order). ## Cancel order To cancel an order in created, notified, or opened status, call the [POST /orders/:id/cancel](/api-reference/orders/cancel-an-order) endpoint. For gifts that are in the accepted state or later, they are already processing; please contact Goody Support for these orders. ## Get order batch You can retrieve an order batch by calling the [GET /order\_batches/:id](/api-reference/order-batches/retrieve-orders-for-an-order-batch) endpoint, or retrieve orders inside the order batch using the [GET /orders/:id/orders](/api-reference/order-batches/retrieve-orders-for-an-order-batch) endpoint. For more information about the other fields in the OrderBatch object, refer to the [OrderBatch schema](/api-reference/schemas/orderbatch). # Automation API: Webhooks Webhooks allow you to be notified when events happen on Goody orders and order batches. You can subscribe to all webhooks, or a subset of them. Webhooks are sent by the Svix platform. In contrast to API keys (which can be created by anyone in the organization and are scoped to users), you must be an organization admin to set up and manage webhooks since they fire on every order and order batch in the organization. ## Set up webhooks To set up webhooks, go to **Organization** on the top right, then **Automation API** in the sub-menu, or click the link for your environment: | Environment | Webhooks Link | | -------------- | ---------------------------------------------------------------------------------------------------------------------------- | | **Production** | [https://www.ongoody.com/plus/organization/api/automation](https://www.ongoody.com/plus/organization/api/automation) | | **Sandbox** | [https://sandbox.ongoody.com/plus/organization/api/automation](https://sandbox.ongoody.com/plus/organization/api/automation) | ## Available webhooks | Webhook | Description | | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | **[order\_batch.created](/webhooks/events/order_batch.created)** | When an order batch is newly created. The order batch could still be in process of sending, or scheduled for the future. | | **[order\_batch.completed](/webhooks/events/order_batch.completed)** | When an order batch is fully processed and all orders have been created. | | **[order.created](/webhooks/events/order.created)** | When an order is created and is ready to be opened. | | **[order.gift\_opened](/webhooks/events/order.gift_opened)** | When a gift is opened by the recipient. | | **[order.gift\_accepted](/webhooks/events/order.gift_accepted)** | When a gift has been accepted by the recipient. | | **[order.thank\_you\_note\_added](/webhooks/events/order.thank_you_note_added)** | When a recipient adds a thank you note to a order after accepting it. | | **[order.shipped](/webhooks/events/order.shipped)** | When an order starts shipping. If there are multiple shipments, this is called for the first. | | **[order.delivered](/webhooks/events/order.delivered)** | When an order is fully delivered. If there are multiple shipments, this is called when all shipments are delivered. | | **[order.canceled](/webhooks/events/order.canceled)** | When an order has been canceled. | | **[order.refunded](/webhooks/events/order.refunded)** | When an order has been refunded. | ## Setting up a new webhook ![](https://mintlify.s3.us-west-1.amazonaws.com/goody/images/new-webhooks.png) Enter a URL to recieve webhooks in the **Endpoint URL** section. You can leave **Message Filtering** blank to receive all events, or select specific events to receive. ## Webhook security To ensure the integrity of the webhooks you receive, we recommend verifying the signatures of the webhooks you receive. Svix provides packages for multiple languages that make verifying signatures easy. To see how, go to the [Webhook Security](/webhooks/webhook-security) page. ## Logs You can view the logs for webhook delivery for each endpoint, and re-send any failed webhooks if needed. ![](https://mintlify.s3.us-west-1.amazonaws.com/goody/images/logs.png) # Automation API: Zapier Create automations without code using Zapier workflows Zapier allows you to connect Goody to more than 5,000+ apps to build automations without code. Some things you can do with Zapier: * Send a gift when a contact is added to a HubSpot list, a new row is added to a Google sheet, or other triggers * Set up automatic rules for sending gifts for things like client anniversaries * Send a Slack message, add to a spreadsheet, and more when a gift is opened, accepted, shipped, or delivered Goody provides several triggers and actions that you can use to connect Goody to the other apps you use. To get started, search for **Goody** when setting up an app as a trigger or action on Zapier. Full documentation for Goody's Zapier app is available on Goody's help center. Learn how to send a gift with Goody's Zapier app. # Commerce API: Access the product catalog To access the product catalog, make a request (using your commerce API key) to: ``` GET https://api.sandbox.ongoody.com/v1/products Authorization: Bearer YOUR_GOODY_COMMERCE_API_KEY ``` This endpoint returns the products that are available to send through the Commerce API. The list of products can change as products are added and removed. The product object includes the brand name, price, brand shipping price, copy like subtitles, variant information, and product imagery. You can paginate the product catalog by passing the `?page=` query parameter (the first page is `1`) and the `?per_page` query parameter (maximum `100`) to paginate through the list. An example response might look like: ```json { "data": [ { "id": "5821e50e-6a56-4144-bca2-3f41fbd699c0", "name": "Dozen Cookies", "brand": { "id": "30e28df2-730e-4763-81bc-d528f0ac6a2a", "name": "Cookie Company", "shipping_price": 1000 }, "subtitle": null, "subtitle_short": null, "recipient_description": "", "variants_label": "Flavor", "variants_num_selectable": 1, "variants": [ { "id": "5eab976a-614c-41cf-a46f-8eca96748fbf", "name": "Chocolate Chip", "subtitle": "Classic chocolate chip.", "image_large": { "url": "https://assets.ongoody.com/image.png", "width": 1000, "height": 500 } }, { "id": "95592e6d-0bd3-49e9-ad2b-0112232e31d6", "name": "Oatmeal", "subtitle": "Delicious oatmeal.", "image_large": { "url": "https://assets.ongoody.com/image.png", "width": 1000, "height": 500 } }, { "id": "fe10b3ac-02b4-4b4e-b5cc-d16303fb1091", "name": "Sugar", "subtitle": "Tasty sugar.", "image_large": { "url": "https://assets.ongoody.com/image.png", "width": 1000, "height": 500 } } ], "images": [ { "id": "4fdc04a5-35e8-4789-84b9-c84259918f36", "image_large": { "url": "https://assets.ongoody.com/image.png", "width": 1000, "height": 500 } } ], "price": 1000, "price_is_variable": false, "restricted_states": [] } ], "list_meta": { "total_count": 1 } } ``` For more information, including the schema of the Product object, check out the [API reference for the products endpoint](/api-reference/products/list-all-active-products). # Commerce API: Authentication Production and Sandbox accounts are separate, and you have different API keys for each environment for isolation. ## Create a Goody for Business account To sign up for a Goody for Business account in production or sandbox, go to the corresponding link: | Environment | API Keys link | | -------------- | ------------------------------------------------------------------------------------------ | | **Production** | [https://www.ongoody.com/business/signup](https://www.ongoody.com/business/signup) | | **Sandbox** | [https://sandbox.ongoody.com/business/signup](https://sandbox.ongoody.com/business/signup) | ## Create a commerce app and API key Once you're signed up, you'll need to create a commerce app and an API key. Next to your account button on the top right, click the **Organization** link, and then navigate to **Commerce API**. | Environment | API Keys link | | -------------- | ------------------------------------------------------------------------------------------------------------------------ | | **Production** | [https://www.ongoody.com/plus/organization/api/commerce](https://www.ongoody.com/plus/organization/api/commerce) | | **Sandbox** | [https://sandbox.ongoody.com/plus/organization/api/commerce](https://sandbox.ongoody.com/plus/organization/api/commerce) | Start by setting a name for your commerce app, and click Create. Then, click **New API key** to generate an API key. ## Base URL The base URL of the API depends on the environment you're using: | Environment | Base URL | | -------------- | ------------------------------------------------------------------ | | **Production** | [https://api.ongoody.com](https://api.ongoody.com) | | **Sandbox** | [https://api.sandbox.ongoody.com](https://api.sandbox.ongoody.com) | ## Authentication header This API uses bearer authentication. Send your API key in the `Authorization` HTTP header preceded by `Bearer `: ``` Authorization: Bearer YOUR_GOODY_COMMERCE_API_KEY ``` ## Calling `/me` To check that you're authenticated, you can send a request to the `/me` endpoint: ``` GET https://api.sandbox.ongoody.com/v1/me Authorization: Bearer YOUR_GOODY_COMMERCE_API_KEY ``` And it should respond with: ```json { "public_app_id": "YOUR_PUBLIC_APP_ID" } ``` # Commerce API: Create an order ## Sending a gift One of the ways you can use the Commerce API is to send a gift. When you send a gift, you can create an order without an address, and you'll get a gift link that you can send to the recipient. The recipient can then enter their own address and accept the gift. To send a gift, you'll want to create what we call an **order batch**. Since Goody lets you send gifts to multiple recipients at once, the "container" for all gifts is an order batch. When you create an order batch, you provide a list of recipients. Each recipient in the gift batch will have an order created for them. If you're sending a single gift at a time, you'll also be creating an order batch – just with one recipient. Think of it as sending an email: whether you're sending an email to one recipient or multiple, you're still composing the same email. The endpoint to create a gift batch is **[POST /v1/order\_batches](/api-reference/order-batches/create-an-order-batch)**: ``` POST https://api.sandbox.ongoody.com/v1/order_batches Authorization: Bearer YOUR_GOODY_COMMERCE_API_KEY ``` Let's take a look at an example payload for creating an order batch: ```json { "from_name": "John", "send_method": "link_multiple_custom_list", "recipients": [ { "first_name": "Alena", "last_name": "Kenter", "email": "alena@ongoody.com" } ], "cart": { "items": [ { "product_id": "9abf2d67-e4f3-4d43-9142-4a1f0d10aaa0", "quantity": 1 } ] }, "payment_method_id": "COMMERCE_STORED_VALUE", "card_id": "ff957080-192d-4032-b4c5-fbb057141c4b", "message": "Thank you!", } ``` These fields are required in each order batch: | Field | Meaning | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `from_name` | **Who is the gift from?** This name is the "from" when the gift is displayed. | | `send_method` | **How do you want to send this gift?** Do you want Goody to send a gift notification email, or just get a link to send on your own? In this case, we're using `link_multiple_custom_list`, which means to get links only without sending an email. For more information, see the Send methods documentation page TK. | | `recipients` | **Who is this gift going to?** If you only have one gift recipient, this array will just have one item. Only `first_name` is required (unless if you want us to send a gift email, in which case you'll also need to provide `email`). | | `cart` | **What products do you want to send in your gift?** Each product you send is an item in the `cart.items` array. You can find Product IDs from the product catalog, or by using [Developer Mode](/introduction/developer-mode) on the Goody website. | | `payment_method_id` | **How do you want to pay for your order?** This is set to `COMMERCE_STORED_VALUE`, which is a special payment method for the Commerce API that gives you a drawdown account. In the sandbox, you have access to this account automatically. In production, you'll need to fund your account with Goody Support before using this. | These fields are optional, but recommended: | Field | Meaning | | --------- | --------------------------------------------- | | `card_id` | (optional) The ID of a digital greeting card. | | `message` | (optional) A message to add to your gift. | ## Create order batch response The response looks like: ```json { "id": "f0903768-609c-4851-bc9a-c17ea245e120", "send_status": "complete", "from_name": "John", "message": "Thank you!", "orders_count": 1, "orders_preview": [ { "id": "a74adf4b-1837-43f5-8e51-f74803cd8832", "status": "created", "recipient_first_name": "Alena", "recipient_last_name": "Kenter", "recipient_email": "alena@ongoody.com", "individual_gift_link": "https://gifts.ongoody.com/gift/gHBMKuXkiVgAFDyXx00h4XGs", "card_id": "ff957080-192d-4032-b4c5-fbb057141c4b", "message": "Thank you!", "thank_you_note": null, "view_count_recipient": 0, "is_swapped": false, "order_batch_id": "f0903768-609c-4851-bc9a-c17ea245e120", "cart": { "id": "fad70b58-896e-4e11-b80b-d807f57e5e3d", "items": [ { "id": "0bc34fa6-d036-4300-a743-dec8eda7f2bd", "quantity": 1, "product": { "id": "9abf2d67-e4f3-4d43-9142-4a1f0d10aaa0", "name": "Cookies", "brand": { "id": "d8782dff-10b2-49ca-87ed-ed6c9d34e4bd", "name": "Cookie Company" } } } ] }, "shipments": [], "amounts": { "amount_product": 1000, "amount_shipping": 1000, "amount_processing_fee": 100, "amount_pre_tax_total": 2100, "amount_tax": null, "amount_total": null, "amount_global_relay_cost": null }, "sender": { "first_name": "Test", "last_name": "User", "email": "15557426864@test.ongoody.com" }, "workspace_id": "b99bf758-104f-4570-a3a9-bc59e64646b1", "workspace_name": "Test Team", "original_cart": null, "original_amounts": null, "reference_id": "5NRQ9IKCVECOHFCUOZWJHTWW" } ], "recipients_count": 1, "recipients_preview": [ { "first_name": "Alena", "last_name": "Kenter", "email": "alena@ongoody.com" } ], "cart": { "id": "fad70b58-896e-4e11-b80b-d807f57e5e3d", "items": [ { "id": "0bc34fa6-d036-4300-a743-dec8eda7f2bd", "quantity": 1, "product": { "id": "9abf2d67-e4f3-4d43-9142-4a1f0d10aaa0", "name": "Cookies", "brand": { "id": "d8782dff-10b2-49ca-87ed-ed6c9d34e4bd", "name": "Cookie Company" } } } ] }, "is_scheduled_send": false, "scheduled_send_on": null, "expires_at": null, "send_method": "link_multiple_custom_list", "batch_name": "Alena Kenter", "card_id": "ff957080-192d-4032-b4c5-fbb057141c4b", "sender": { "first_name": "Commerce", "last_name": "User", "email": "15557426864@ongoody.com" }, "workspace_id": "b99bf758-104f-4570-a3a9-bc59e64646b1", "workspace_name": "Test Team", "reference_id": "XNYLJMW5JIFOFRM0PQIPNA56" } ``` * **If you send an order batch with 10 or fewer recipients**, orders are processed right away, and you'll see that that `send_status` is `complete` and you'll receive the list of orders back in the `orders_preview` object. * **If you send an order batch with more than 10 recipients**, creating orders happens asynchronously in the background, and you'll see that `send_status` is `pending`. You can hit the [`/order_batches/:id`](/api-reference/order-batches/retrieve-an-order-batch) endpoint to check the `send_status` for `complete`, or listen for the `order_batch.completed` webhook. * The `orders_preview` endpoint only contains the first 10 orders. If you have more orders, you can paginate through all the orders using the [`/order_batches/:id/orders`](/api-reference/order-batches/retrieve-orders-for-an-order-batch) endpoint. * **If you schedule an order batch for the future** using the `scheduled_send_on` parameter, the `send_status` will be `pending`, and `orders_preview` will be empty, until the scheduled send time, at which point the orders are created. Similarly to above, you can listen for the `order_batch.completed` webhook. You can check the `send_status` field to determine if your order batch is being asynchronously processed or is scheduled for the future (`send_status == pending`) or orders are ready (`send_status == complete`). ### The `orders_preview` field The most important thing in the response is the order object. The `orders_preview` field displays the first 10 orders in your order batch. To determine the number of orders in the order batch, you can use the `orders_count` field. ```json "orders_count": 1, "orders_preview": [ { "id": "a74adf4b-1837-43f5-8e51-f74803cd8832", "status": "created", "recipient_first_name": "Alena", "recipient_last_name": "Kenter", "recipient_email": "alena@ongoody.com", "individual_order_link": "https://gifts.ongoody.com/gift/gHBMKuXkiVgAFDyXx00h4XGs", "card_id": "ff957080-192d-4032-b4c5-fbb057141c4b", "message": "Thank you!", "thank_you_note": null, "view_count_recipient": 0, "is_swapped": false, "order_batch_id": "f0903768-609c-4851-bc9a-c17ea245e120", "cart": { ... }, "shipments": [], "amounts": { "amount_product": 1000, "amount_shipping": 1000, "amount_processing_fee": 100, "amount_pre_tax_total": 2100, "amount_tax": null, "amount_total": null, "amount_global_relay_cost": null }, "sender": { "first_name": "Test", "last_name": "User", "email": "15557426864@test.ongoody.com" }, "workspace_id": "b99bf758-104f-4570-a3a9-bc59e64646b1", "workspace_name": "Test Team", "original_cart": null, "original_amounts": null, "reference_id": "5NRQ9IKCVECOHFCUOZWJHTWW" }, ] ``` If you always send single orders or fewer than 10 orders at once, great! You can use this array without having to make another request. But if you send more than 10 orders at once, you can also hit the [`/order_batches/:id/orders`](../../goody-api-openapi.json/paths/~1v1~1order_batches~1\{id}~1orders) endpoint to paginate through the rest of your orders. In the order object, there are a few fields to point out: * `individual_gift_link` — This is the individual gift link for that recipient, which when opened goes directly to their gift. You can send this in an email or somewhere else so they can access their gift. * `status` — This status is for the individual order itself. The list of order statuses can be viewed on the [order lifecycle guide](/introduction/order-lifecycle). You can set up webhooks to get notified on changes to the status. * `amounts` — Contains the costs for this order, in cents. Congratulations – you've sent a gift! For more information on the order batch send endpoint, [visit the doc](/api-reference/~1v1~1order_batches). ## Next steps Now that you've sent your gift, you can now open the gift link and accept the gift to see what the experience looks like. # Goody Commerce API Sell physical products in your app without handling inventory, vendor partnerships, or logistics, and earn a revenue share on orders. * **Access our product catalog** — We've built partnerships and revenue share agreements to carry brands like Brooklinen, Apple, MALIN+GOETZ, Levain Bakery, Bose, and more, so you don't have to. Access our product catalog with full product imagery and descriptions. * **Sell physical products in your app** — Display our full catalog or curate your own selection. Programmatically create orders through the Commerce API. * **Send gifts without an address** — Use our gifting flow to create a gift without an address. Generate a gift link that a recipient can use to accept their gift, swap for another gift, select personalized options like color or size, and more. * **Ship orders directly to an address** — If you know the address, we support that too. Just submit an API request – we handle the logistics and notify you when it's delivered. (Revenue share requires an agreement. Please contact our business development team before you go live.) ## Payments The Commerce API is flexible on how to collect payments from end customers and how we pay the revenue share: | Method | Description | | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Partner app collects payment** | If you want to capture payment information or already have customer cards on file, you can process payments yourself. We set up a prefunded payment account for you on Goody. Once an order is placed with Goody, the transaction is paid for (with revshare credited) through the prefunded account. | | **Partner app passes credit card information** | If you want to capture payment information or already have customer cards on file, but you want us to process the payment, you can send customer credit card details to our secure payment environment in Stripe. We will process the payment, and record revenue share and pay the revshare via bank transfer. | | **Goody captures credit card information** | If you don't want to capture payment information, we can provide a secure Stripe payment form for end customers. We will process the payment, and record revenue share and pay the revshare via bank transfer. | ## Getting started In this guide, we'll walk through how to: 1. Set up an account on our sandbox environment 2. Obtain an API key 3. Send a gift 4. Set up webhooks for order events. Let's start with setting up an account and authentication. # Commerce API: Payment The Commerce API supports three payment modes: * [Stored Value](#stored-value) * [Hosted Payment](#hosted-payment) * [Tokenized Payment](#tokenized-payment) ## Stored Value The Stored Value payment mode is typically used when you capture payment on your own platform from your customer. It relies on a stored value balance deposited with Goody. Revenue share is credited back to the same account, so no additional revenue share reconciliation is required. 1. Create an order batch with `payment_method_id` set to `COMMERCE_STORED_VALUE`. 2. Capture payment from your customer on your own platform. 3. Once the order is accepted, the cost of the order will be deducted from your stored value account. 4. Then, the revenue share will be paid into the stored value account as a separate transaction, so it can be easily separated out in your reports. Stored Value in the sandbox is test money and can be used freely. If you want to set up stored value in the sandbox, contact your partnerships manager or [support@ongoody.com](mailto:support@ongoody.com) and we'll add some money into your account. To deposit stored value in production, contact your partnerships manager or [support@ongoody.com](mailto:support@ongoody.com). ## Hosted Payment The Hosted Payment mode allows you to use Goody's payment processing page once an order (typically a gift) is accepted by the recipient. 1. Create an order batch with `payment_method_id` set to `COMMERCE_HOSTED_PAYMENT`. 2. When the gift is accepted, receive the `order.accepted` webhook. The webhook payload will show that the order is in `pending_payment` status and will contain a `payment_link` field. This field is also available on the `Order` object in the [retrieve an order](/api-reference/orders/retrieve-an-order) endpoint. 3. Send your customer the `payment_link` URL, which will contain the final cost of the order and a credit card form. 4. Once the customer completes payment, the order will move to `paid` status. ## Tokenized Payment Tokenized payment is available for approved partners. It will allow you to pass credit card details directly from your own platform to Goody's payment processor. Please contact us directly if you have a use case for this. # Commerce API: Retrieve order status ## Get order In most cases, you'll want to get information about an individual order. You can retrieve an order by calling the [GET /orders/:id](/api-reference/orders/retrieve-an-order) endpoint. This will return all information about the order, in particular its status, such as `notified`, `opened`, `shipped`, `delivered`, etc. For more information on all of the available order statuses, visit the [Order Lifecycle](/introduction/order-lifecycle) documentation page. For more information about the other fields in the Order object, refer to the [Order schema](/api-reference/schemas/order). ## Cancel order To cancel an order in `created`, `notified`, or `opened` status, call the [POST /orders/:id/cancel](/api-reference/orders/cancel-an-order) endpoint. For gifts that are in the `accepted` state or later, they are already processing; please contact Goody Support for these orders. ## Get order batch You can retrieve an order batch by calling the [GET /order\_batches/:id](/api-reference/orders/retrieve-an-order) endpoint, or retrieve orders inside the order batch using the [GET /orders/:id/orders](/api-reference/order-batches/retrieve-orders-for-an-order-batch) endpoint. For more information about the other fields in the OrderBatch object, refer to the [OrderBatch schema](/api-reference/schemas/orderbatch). # Commerce API: Webhooks Webhooks allow you to be notified when events happen on Goody orders and order batches. You can subscribe to all webhooks, or a subset of them. Webhooks are sent by the Svix platform. ## Set up webhooks To set up webhooks, go to **Organization** on the top right, then **Commerce API** in the sub-menu, or click the link for your environment: | Environment | Webhooks link | | -------------- | ------------------------------------------------------------------------------------------------------------------------ | | **Production** | [https://www.ongoody.com/plus/organization/api/commerce](https://www.ongoody.com/plus/organization/api/commerce) | | **Sandbox** | [https://sandbox.ongoody.com/plus/organization/api/commerce](https://sandbox.ongoody.com/plus/organization/api/commerce) | Then, click the commerce app you have set up. ## Available webhooks | Webhook | Description | | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | **[order\_batch.created](/webhooks/events/order_batch.created)** | When an order batch is newly created. The order batch could still be in process of sending, or scheduled for the future. | | **[order\_batch.completed](/webhooks/events/order_batch.completed)** | When an order batch is fully processed and all orders have been created. | | **[order.created](/webhooks/events/order.created)** | When an order is created and is ready to be opened. | | **[order.gift\_opened](/webhooks/events/order.gift_opened)** | When a gift is opened by the recipient. | | **[order.gift\_accepted](/webhooks/events/order.gift_accepted)** | When a gift has been accepted by the recipient. | | **[order.thank\_you\_note\_added](/webhooks/events/order.thank_you_note_added)** | When a recipient adds a thank you note to a order after accepting it. | | **[order.shipped](/webhooks/events/order.shipped)** | When an order starts shipping. If there are multiple shipments, this is called for the first. | | **[order.delivered](/webhooks/events/order.delivered)** | When an order is fully delivered. If there are multiple shipments, this is called when all shipments are delivered. | | **[order.canceled](/webhooks/events/order.canceled)** | When an order has been canceled. | | **[order.refunded](/webhooks/events/order.refunded)** | When an order has been refunded. | ## Setting up a new webhook ![](https://mintlify.s3.us-west-1.amazonaws.com/goody/images/new-webhook-2.png) Enter a URL to recieve webhooks in the **Endpoint URL** section. You can leave **Message Filtering** blank to receive all events, or select specific events to receive. ## Webhook security To ensure the integrity of the webhooks you receive, we recommend verifying the signatures of the webhooks you receive. Svix provides packages for multiple languages that make verifying signatures easy. To see how, go to the [Webhook Security](/webhooks/webhook-security) page. ## Logs You can view the logs for webhook delivery for each endpoint, and re-send any failed webhooks if needed. ![webhook-logs.png](https://mintlify.s3.us-west-1.amazonaws.com/goody/images/logs-2.png) # Developer mode Enable Developer Mode on the Goody website to get product IDs and card IDs. You can use Developer Mode on the Goody website to: * Find product IDs to add to a create order batch payload * Find the ID of digital greeting cards to add to a create order batch payload * Obtain a cart payload from the contents of your Goody cart ## Enable Developer Mode 1. Go to your Account menu by clicking the user icon on the top-left of the Goody website, and then click **My Account**. 2. Click the **API Keys** menu item on the account sub-menu. 3. Under **Developer Mode**, click **Enable developer mode**. ![Enable developer mode button](https://mintlify.s3.us-west-1.amazonaws.com/goody/images/developer-mode.png) ## Find product IDs When clicking into a product page with Developer Mode enabled, the Product ID is displayed below the product name. ![Product ID on product page](https://mintlify.s3.us-west-1.amazonaws.com/goody/images/developer-mode-product-id-product.png) Some products don't have dedicated product pages. For those products, the product ID is located at the bottom of the brand window. ## Find card IDs Go to the **Send** page and click the **Select card** button, which might be **Edit card** if you've already selected a card. ![Select card button](https://mintlify.s3.us-west-1.amazonaws.com/goody/images/developer-mode-send-card.png) Card IDs are displayed below the card image. ![Card IDs](https://mintlify.s3.us-west-1.amazonaws.com/goody/images/developer-mode-card-id.png) ## Get cart payload Once you've added products to your cart, you can click the bag icon at the top right to open your cart. The JSON cart payload for the items you've selected is displayed at the bottom of the cart. # Order lifecycle ## Orders The status for an order can be found on the `status` field. | Status | Meaning | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `created` | The gift has been created. | | `notified` | Notifications (e.g. email or text) have been sent for this order, if requested. If no notifications are requested, orders will still move to this state without sending notifications. | | `opened` | For gift orders: the recipient has opened a gift. | | `accepted` | For gift orders: the recipient has accepted the gift. For other orders: the order has been accepted for processing. | | `pending_payment` | The order is awaiting payment. If a payment method has been specified, it will be processed at this stage. | | `paid` | The order has been paid for and is being prepared for shipment. | | `shipped` | The order has shipped. If the order has multiple shipments, it will enter this state when the first shipment starts moving. | | `delivered` | The order has been delivered. If the order has multiple shipments, it will enter this state when all shipments have been delivered. | | `failed` | The order has been canceled. This status will show up if you cancel an order using the cancel order endpoint. | ## Order batches Order batches are collections of orders. The order batch's `send_status` displays the status of the order batch. | Status | Meaning | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `pending` | For non-scheduled order batches, the order batch is being processed to create orders for each recipient. For scheduled order batches, the order batch is waiting for the scheduled time to send. | | `complete` | The order batch has been created and all orders have been created for all recipients. | ## Testing shipped and delivered statuses, and refunds In the sandbox only, we provide some *magic words* for testing `shipped` and `delivered` orders. When you enter a specific from name, the order will be moved to shipped or delivered after it's accepted. Here's how to use it: 1. Create the order batch with `from_name` set to `[shipped]` or `[delivered]`. 2. Open the gift link and accept the gift. 3. Shortly after the gift is accepted, the order will move to Shipped or Delivered, depending on the magic word you use. To test the refund webhook, you can also use the magic word `[refunded]` by creating an order batch with that `from_name`. This will cause the order to be refunded after it's accepted. # Goody API Goody's API lets you send physical products and gifts programmatically. * **Send gifts without an address**. You can generate a gift link where they can view your gift, have the option of swapping it for something else, and enter their address themselves * **Ship physical products to an address**. If you already have an address, Goody can ship products and handle all the logistics. ## Available APIs Goody provides two APIs depending on your use case: Sell physical products in your app without handling inventory, partnerships, or logistics. Access our product catalog, gift without an address, and earn a revenue share. Automate your own gifting and sending. Create custom integrations to send one or hundreds of gifts programmatically. Or use our Zapier app for no-code workflows. ## Production and sandbox environments Goody's API has two environments: * **Production**: [https://api.ongoody.com](https://api.ongoody.com) * **Sandbox**: [https://sandbox.api.ongoody.com](https://sandbox.api.ongoody.com) ## Start using the API To start using the API, sign up for a Goody for Business account at [https://www.ongoody.com/business](https://www.ongoody.com/business). It's free to sign up. To obtain an API key for the Automation API, go to your Account page and click [API Keys](https://www.ongoody.com/plus/account/api-keys). To send gifts in production, you'll need to add a payment method, which you can do on that page. To obtain an API key for the Commerce API, refer to the [getting started guide](/commerce-api/overview). ## Using the Sandbox environment You can use the Sandbox environment to send test gifts without being charged for them. Your sandbox account is entirely separate account from production, so you can do your testing without affecting your main account. Visit [https://sandbox.ongoody.com/business](https://sandbox.ongoody.com/business) to sign up for a sandbox account, and to obtain an API key for the Automation API, go to your Account page and click [API Keys](https://sandbox.ongoody.com/plus/account/api-keys). To obtain an API key for the Commerce API, refer to the [getting started guide](/commerce-api/overview). ## OpenAPI file Goody provides an OpenAPI (Swagger) file that you can import to various tools like Postman and Insomnia. [Download OpenAPI file](https://assets.ongoody.com/static/web/goody-api-openapi.json) # Send methods When creating an order batch, there are several send methods that define the behavior of orders. The send method (`email_and_link`, `link_multiple_custom_list`, or `direct_send`) is passed as the `send_method` field on the [create order batch payload](/api-reference/order-batches/create-an-order-batch). **Available send methods** ## Gift – Email Notification Send method: `email_and_link` Orders will be created as gifts. An email notification (and text message, if phone is specified) will be sent to the recipient of the gift. You will also be able to retrieve the gift link from the `individual_gift_link` field on the `Order` object (hence "email and link"). An email must be specified for every recipient. Gift recipients can view their gift, swap for another gift (if swap is not disabled), and accept the gift by entering their address. ## Gift – Links Only Send method: `link_multiple_custom_list` Orders will be created as gifts. No email notification will be sent to the gift recipient. On the `Order` object, there will be an `individual_gift_link` field which contains the link to the gift, which you can send to the recipient. Gift recipients can view their gift, swap for another gift (if swap is not disabled), and accept the gift by entering their address. ## Direct Send **Direct Send is limited to approved partners**. Contact us if you want to use direct send for your integration. Send method: `direct_send` Ship products directly to the given address. For more info, see the [documentation page for direct send](/introduction/send-to-address). The address must be specified in the `mailing_address` field of the recipient payload, like the example below: ```json "recipients": [ { "first_name": "Alena", "last_name": "Kenter", "email": "alena@ongoody.com", "mailing_address": { "first_name": "Alena", "last_name": "Kenter", "address_1": "1 Main St", "address_2": "Apt 123", "city": "New York", "state": "NY", "postal_code": "10022", "country": "US" } } ] ``` # Ship to address Ship products directly to an address with the Direct Send send method. When you already know the address you want to send an order to, you can use Goody to ship directly to that address using the Direct Send send method (`direct_send`). There are two things to be aware of when using direct send: 1. You'll enter the address of the recipient in the `mailing_address` field of the recipient object. 2. If a product in your cart has variants, you must specify the variants to send. ## Specifying the mailing address To specify the mailing address, you'll need to add a `mailing_address` object to the recipient object. Here's an example: ```json "recipients": [ { "first_name": "Alena", "last_name": "Kenter", "email": "alena@ongoody.com", "mailing_address": { "first_name": "Alena", "last_name": "Kenter", "address_1": "1 Main St", "address_2": "Apt 123", "city": "New York", "state": "NY", "postal_code": "10022", "country": "US" } } ] ``` ## Specifying variants When sending a gift with Goody, you don't need to specify the variants since the recipient can select the variants on their own. However, when sending with Direct Send, we need to know which variant to send to the recipient, so you'll need to specify the variant. If a product has no variants (`variants_num_selectable` is null or zero), you don't need to specify any variants. ### Variants data When [retrieving products from the product catalog](/api-reference/products/list-all-active-products), you'll see the following information in the product object: ```json { "variants_label": "Flavor", "variants_num_selectable": 1, "variants": [ { "id": "4da4dfd2-a094-4f9b-80dc-11d9067ff41b", "name": "Chocolate Chip", "subtitle": "Classic chocolate chip.", "image_large": null }, { "id": "4d2581b7-b127-4e4b-8fac-7c7835022e3d", "name": "Oatmeal", "subtitle": "Delicious oatmeal.", "image_large": null }, { "id": "087da4f9-8f8b-4d36-96b2-498a5b906409", "name": "Sugar", "subtitle": "Tasty sugar.", "image_large": null } } ``` `variants_label` tells you the name of the variant. This can be something like Size, Flavor, Color, etc. `variants_num_selectable` tells you how many variants can be selected. This is the expected length of the `variants` array that you pass into the cart item. Typically, this is 1, but some products let you select more than one variant, such as a 3-pack of cookies. If this is null or `0`, then you don't need to specify any variants. `variants` shows you the data for each variant. You'll use the `name` field of the variant when passing variants in the cart item. ### Adding variants to the cart item Let's say that the product has `variants_num_selectable` equal to `1`, so we must specify one variant in the cart item. Our cart item now looks like this: ```json "cart": { "items": [ { "product_id": "0b7b7cb3-a8c5-456f-af88-ae73f25092a5", "quantity": 1, "variants": ["Chocolate Chip"] } ] } ``` Now, if we had a product with `variants_num_selectable` equal to `3`, then we must specify three variants in the cart item. Our cart item now looks like this: ```json "cart": { "items": [ { "product_id": "0b7b7cb3-a8c5-456f-af88-ae73f25092a5", "quantity": 1, "variants": ["Chocolate Chip", "Sugar", "Sugar"] } ] } ``` You can specify the same variant more than once. ## Example direct send payload This payload will send a direct send gift to the specified recipient. This product is a pack of cookies with a single variant selection (`variants_num_selectable` is `1`). ```json { "from_name": "Michael", "send_method": "direct_send", "recipients": [ { "first_name": "Alena", "last_name": "Kenter", "email": "alena@ongoody.com", "mailing_address": { "first_name": "Alena", "last_name": "Kenter", "mailing_address": { "address_1": "1 Main St", "address_2": "Apt 123", "city": "New York", "state": "NY", "postal_code": "10022", "country": "US" } } } ], "cart": { "items": [ { "product_id": "5ab8967a-0add-426f-a50c-8032b8bae643", "quantity": 1, "variants": ["Bestsellers Mix"] } ] } } ``` # Changelog Updates to the Goody API ### September 10, 2024 * Add `custom_catalog_show_inactive` parameter to the [List all active products (/v1/products)](https://developer.ongoody.com/api-reference/products/list-all-active-products) endpoint (Commerce API custom catalogs only). * Add `updated_at` and `status` (Commerce API custom catalogs only) fields to the [Product schema](https://developer.ongoody.com/api-reference/schemas/product). `status` is only for custom catalogs; by default, all products returned are active, unless when using the `custom_catalog_show_inactive` parameter. ### August 28, 2024 * Add `variant_groups` field to the Product schema. ### August 8, 2024 * Add `international_shipping_tier` and `international_gift_cards_enabled` fields to Order Batch Create payload. # Event: order.canceled Emitted when an order has been canceled. ## Example ```json { "event_type": "order.canceled", "id": "ad097c47-bf12-45c9-8feb-0536a0012c09", "data": { "id": "8999f804-d731-440d-a67d-35444c12c493", "status": "failed", "individual_gift_link": "https://gifts.ongoody.com/gift/IsDyQQWtqrOyGPgZ9bVm6ptz", "recipient_first_name": "Alena", "recipient_last_name": "Kenter", "recipient_email": "alena@ongoody.com", "card_id": "7e79fd96-212b-4468-9989-57b896ca22f4", "message": "Thank you!", "thank_you_note": null, "view_count_recipient": 0, "is_swapped": false, "order_batch_id": "d158184c-6b31-4a72-b39f-8f8ca04ecbdd", "expires_at": null, "cart": { "id": "3ff7dab1-ae03-4b20-a2c8-82a3f3326b83", "items": [ { "id": "284dc74f-a2c4-4b62-bfe5-94c464d56ea7", "quantity": 1, "product": { "id": "10227d72-c355-4881-8007-aad34f501055", "name": "Cookies", "brand": { "id": "fe370ec6-1208-4d23-b936-de857ceeae6d", "name": "Cookie Company" } } } ] }, "shipments": [], "amounts": { "amount_product": 1000, "amount_shipping": 1000, "amount_processing_fee": 100, "amount_pre_tax_total": 2100, "amount_tax": null, "amount_total": null, "amount_global_relay_cost": null }, "sender": { "first_name": "Test", "last_name": "User", "email": "15551494889@test.ongoody.com" }, "workspace_id": "dfe0d5cb-2c98-4800-a950-b40cca509250", "workspace_name": "Test Team", "original_cart": null, "original_amounts": null, "reference_id": "2MUPN0YMGIDT7TJNPPFPB7WE" } } ``` ## Schema The type of event that occurred The unique ID for this event An individual order contains the gift link to be sent to the recipient (if applicable) and other information about the order. Allowed values: `created` `notified` `opened` `accepted` `pending_payment` `paid` `ordered` `shipped` `delivered` `failed` `canceled` 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. 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). The brand that this product is from. A list of the shipments for the order. Allowed values: `pending` `tracking` `shipped` `delivered` `delivered_override` `failed` `failed_unset_tracking` `failed_with_reship` The name of the brand that this shipment is from The carrier for this shipment, e.g. UPS. Only for approved distribution partners. ISO 8601 ISO 8601 The estimated delivery time of this shipment. Organizations are sub-divided into workspaces. Orders are contained in workspaces, identified by this ID. For gifts, the date and time the gift is set to expire. The digital greeting card on this gift. The message in this gift, provided by the sender. A thank you note sent by the recipient. The number of times the recipient viewed the gift. 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`. On Goody for Business, all orders are attached to a order batch, which is a collection of one or more orders. Costs in USD cents (i.e. \$1.00 = 100). If the order was swapped, `amounts` displays the most recent amounts (i.e. post-swap). Total cost of the products in this order. Total cost of shipping for this order. Total cost of processing fees for this order. Total amount of credit applied to this order. Total cost of the products, shipping, and processing fees in this order. Total tax for this order. Total cost of the products, shipping, processing fees, tax, and global shipping costs in this order. Total cost of global shipping for this order through the Global Relay service. Only provided when calling the /orders/:id endpoint. ISO 8601 When the recipient was notified of the order. For gifts, when the recipient opened the order. For gifts, when the recipient accepted the order. When the order entered pending payment status. When the order was paid for. When the order was first shipped. If there are multiple shipments, this is when the first shipment shipped. When the order was delivered. If there are multiple shipments, this is when all shipments were delivered. If this order is a gift that was swapped, this displays the original cart that was sent to the recipient. The brand that this product is from. If this order is a gift that was swapped, this displays the original amounts of the cart that was sent to the recipient. The Goody user who sent this order. The reference ID displayed on receipts and other locations as the ID for this order. # Event: order.created Emitted when an order has been created and is ready to be opened and accepted (if it's a gift). An individual gift link is available (`individual_gift_link`). ## Example ```json { "event_type": "order.created", "id": "ad097c47-bf12-45c9-8feb-0536a0012c09", "data": { "id": "10c588dd-d566-45bf-86e9-c23bd1f1587b", "status": "created", "individual_gift_link": "https://gifts.ongoody.com/gift/vWtUe8lQRJuoyYzKlYeHMkbV", "recipient_first_name": "Alena", "recipient_last_name": "Kenter", "recipient_email": "alena@ongoody.com", "card_id": "ae4cb4ce-75fc-4782-a9ab-2f30d9b7b41d", "message": "Thank you!", "thank_you_note": null, "view_count_recipient": 0, "is_swapped": false, "order_batch_id": "4133078a-c35f-441e-8e92-57645342b299", "expires_at": null, "cart": { "id": "39b04e91-6a40-468d-8ed4-f59e9059afae", "items": [ { "id": "d59dead0-a44c-44df-885f-030612038a48", "quantity": 1, "product": { "id": "c399bafb-3fbc-40c5-bef3-9158b7a19abc", "name": "Cookies", "brand": { "id": "db631527-c59c-409c-823f-42a24c972283", "name": "Cookie Company" } } } ] }, "shipments": [], "amounts": { "amount_product": 1000, "amount_shipping": 1000, "amount_processing_fee": 100, "amount_pre_tax_total": 2100, "amount_tax": null, "amount_total": null, "amount_global_relay_cost": null }, "sender": { "first_name": "Test", "last_name": "User", "email": "15556038009@test.ongoody.com" }, "workspace_id": "8779bb01-ca47-4e9e-a845-d05f509c4be3", "workspace_name": "Test Team", "original_cart": null, "original_amounts": null, "reference_id": "PCI7GLZ3KFIEN8MWWSD5LDCF" } } ``` ## Schema The type of event that occurred The unique ID for this event An individual order contains the gift link to be sent to the recipient (if applicable) and other information about the order. Allowed values: `created` `notified` `opened` `accepted` `pending_payment` `paid` `ordered` `shipped` `delivered` `failed` `canceled` 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. 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). The brand that this product is from. A list of the shipments for the order. Allowed values: `pending` `tracking` `shipped` `delivered` `delivered_override` `failed` `failed_unset_tracking` `failed_with_reship` The name of the brand that this shipment is from The carrier for this shipment, e.g. UPS. Only for approved distribution partners. ISO 8601 ISO 8601 The estimated delivery time of this shipment. Organizations are sub-divided into workspaces. Orders are contained in workspaces, identified by this ID. For gifts, the date and time the gift is set to expire. The digital greeting card on this gift. The message in this gift, provided by the sender. A thank you note sent by the recipient. The number of times the recipient viewed the gift. 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`. On Goody for Business, all orders are attached to a order batch, which is a collection of one or more orders. Costs in USD cents (i.e. \$1.00 = 100). If the order was swapped, `amounts` displays the most recent amounts (i.e. post-swap). Total cost of the products in this order. Total cost of shipping for this order. Total cost of processing fees for this order. Total amount of credit applied to this order. Total cost of the products, shipping, and processing fees in this order. Total tax for this order. Total cost of the products, shipping, processing fees, tax, and global shipping costs in this order. Total cost of global shipping for this order through the Global Relay service. Only provided when calling the /orders/:id endpoint. ISO 8601 When the recipient was notified of the order. For gifts, when the recipient opened the order. For gifts, when the recipient accepted the order. When the order entered pending payment status. When the order was paid for. When the order was first shipped. If there are multiple shipments, this is when the first shipment shipped. When the order was delivered. If there are multiple shipments, this is when all shipments were delivered. If this order is a gift that was swapped, this displays the original cart that was sent to the recipient. The brand that this product is from. If this order is a gift that was swapped, this displays the original amounts of the cart that was sent to the recipient. The Goody user who sent this order. The reference ID displayed on receipts and other locations as the ID for this order. # Event: order.delivered Emitted when an order has been delivered. If the order has multiple shipments, this is emitted when all shipments have been delivered. ## Example ```json { "event_type": "order.delivered", "id": "ad097c47-bf12-45c9-8feb-0536a0012c09", "data": { "id": "10c588dd-d566-45bf-86e9-c23bd1f1587b", "status": "shipped", "individual_gift_link": "https://gifts.ongoody.com/gift/vWtUe8lQRJuoyYzKlYeHMkbV", "recipient_first_name": "Alena", "recipient_last_name": "Kenter", "recipient_email": "alena@ongoody.com", "card_id": "ae4cb4ce-75fc-4782-a9ab-2f30d9b7b41d", "message": "Thank you!", "thank_you_note": null, "view_count_recipient": 0, "is_swapped": false, "order_batch_id": "4133078a-c35f-441e-8e92-57645342b299", "expires_at": null, "cart": { "id": "39b04e91-6a40-468d-8ed4-f59e9059afae", "items": [ { "id": "d59dead0-a44c-44df-885f-030612038a48", "quantity": 1, "product": { "id": "c399bafb-3fbc-40c5-bef3-9158b7a19abc", "name": "Cookies", "brand": { "id": "db631527-c59c-409c-823f-42a24c972283", "name": "Cookie Company" } } } ] }, "shipments": [ { "id": "9a1a2003-bb03-4409-b7fd-243b2e600e46", "status": "delivered", "brand_name": "Cookie Company", "tracking_carrier": "UPS", "shipped_at": "2023-01-23T00:00:00Z", "delivered_at": "2023-01-26T00:00:00Z", "delivery_eta": "2023-01-26T00:00:00Z" } ], "amounts": { "amount_product": 1000, "amount_shipping": 1000, "amount_processing_fee": 100, "amount_pre_tax_total": 2100, "amount_tax": 150, "amount_total": 2250, "amount_global_relay_cost": null }, "sender": { "first_name": "Test", "last_name": "User", "email": "15556038009@test.ongoody.com" }, "workspace_id": "8779bb01-ca47-4e9e-a845-d05f509c4be3", "workspace_name": "Test Team", "original_cart": null, "original_amounts": null, "reference_id": "PCI7GLZ3KFIEN8MWWSD5LDCF" } } ``` ## Schema The type of event that occurred The unique ID for this event An individual order contains the gift link to be sent to the recipient (if applicable) and other information about the order. Allowed values: `created` `notified` `opened` `accepted` `pending_payment` `paid` `ordered` `shipped` `delivered` `failed` `canceled` 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. 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). The brand that this product is from. A list of the shipments for the order. Allowed values: `pending` `tracking` `shipped` `delivered` `delivered_override` `failed` `failed_unset_tracking` `failed_with_reship` The name of the brand that this shipment is from The carrier for this shipment, e.g. UPS. Only for approved distribution partners. ISO 8601 ISO 8601 The estimated delivery time of this shipment. Organizations are sub-divided into workspaces. Orders are contained in workspaces, identified by this ID. For gifts, the date and time the gift is set to expire. The digital greeting card on this gift. The message in this gift, provided by the sender. A thank you note sent by the recipient. The number of times the recipient viewed the gift. 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`. On Goody for Business, all orders are attached to a order batch, which is a collection of one or more orders. Costs in USD cents (i.e. \$1.00 = 100). If the order was swapped, `amounts` displays the most recent amounts (i.e. post-swap). Total cost of the products in this order. Total cost of shipping for this order. Total cost of processing fees for this order. Total amount of credit applied to this order. Total cost of the products, shipping, and processing fees in this order. Total tax for this order. Total cost of the products, shipping, processing fees, tax, and global shipping costs in this order. Total cost of global shipping for this order through the Global Relay service. Only provided when calling the /orders/:id endpoint. ISO 8601 When the recipient was notified of the order. For gifts, when the recipient opened the order. For gifts, when the recipient accepted the order. When the order entered pending payment status. When the order was paid for. When the order was first shipped. If there are multiple shipments, this is when the first shipment shipped. When the order was delivered. If there are multiple shipments, this is when all shipments were delivered. If this order is a gift that was swapped, this displays the original cart that was sent to the recipient. The brand that this product is from. If this order is a gift that was swapped, this displays the original amounts of the cart that was sent to the recipient. The Goody user who sent this order. The reference ID displayed on receipts and other locations as the ID for this order. # Event: order.gift_accepted Emitted when a gift has been accepted by a recipient, and the final costs of the order have been calculated. You can also view whether they swapped the gift (`is_swapped`) and what they swapped to (`cart`). ## Example ```json { "event_type": "order.gift_accepted", "id": "ad097c47-bf12-45c9-8feb-0536a0012c09", "data": { "id": "10c588dd-d566-45bf-86e9-c23bd1f1587b", "status": "accepted", "individual_gift_link": "https://gifts.ongoody.com/gift/vWtUe8lQRJuoyYzKlYeHMkbV", "recipient_first_name": "Alena", "recipient_last_name": "Kenter", "recipient_email": "alena@ongoody.com", "card_id": "ae4cb4ce-75fc-4782-a9ab-2f30d9b7b41d", "message": "Thank you!", "thank_you_note": null, "view_count_recipient": 0, "is_swapped": false, "order_batch_id": "4133078a-c35f-441e-8e92-57645342b299", "expires_at": null, "cart": { "id": "39b04e91-6a40-468d-8ed4-f59e9059afae", "items": [ { "id": "d59dead0-a44c-44df-885f-030612038a48", "quantity": 1, "product": { "id": "c399bafb-3fbc-40c5-bef3-9158b7a19abc", "name": "Cookies", "brand": { "id": "db631527-c59c-409c-823f-42a24c972283", "name": "Cookie Company" } } } ] }, "shipments": [], "amounts": { "amount_product": 1000, "amount_shipping": 1000, "amount_processing_fee": 100, "amount_pre_tax_total": 2100, "amount_tax": 150, "amount_total": 2250, "amount_global_relay_cost": null }, "sender": { "first_name": "Test", "last_name": "User", "email": "15556038009@test.ongoody.com" }, "workspace_id": "8779bb01-ca47-4e9e-a845-d05f509c4be3", "workspace_name": "Test Team", "original_cart": null, "original_amounts": null, "payment_link": "https://checkout.ongoody.com/checkout?key=1on1dhtA3LekJgvxNZu83XqN", "reference_id": "PCI7GLZ3KFIEN8MWWSD5LDCF" } } ``` ## Schema The type of event that occurred The unique ID for this event An individual order contains the gift link to be sent to the recipient (if applicable) and other information about the order. Allowed values: `created` `notified` `opened` `accepted` `pending_payment` `paid` `ordered` `shipped` `delivered` `failed` `canceled` 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. 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). The brand that this product is from. A list of the shipments for the order. Allowed values: `pending` `tracking` `shipped` `delivered` `delivered_override` `failed` `failed_unset_tracking` `failed_with_reship` The name of the brand that this shipment is from The carrier for this shipment, e.g. UPS. Only for approved distribution partners. ISO 8601 ISO 8601 The estimated delivery time of this shipment. Organizations are sub-divided into workspaces. Orders are contained in workspaces, identified by this ID. For gifts, the date and time the gift is set to expire. The digital greeting card on this gift. The message in this gift, provided by the sender. A thank you note sent by the recipient. The number of times the recipient viewed the gift. 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`. On Goody for Business, all orders are attached to a order batch, which is a collection of one or more orders. Costs in USD cents (i.e. \$1.00 = 100). If the order was swapped, `amounts` displays the most recent amounts (i.e. post-swap). Total cost of the products in this order. Total cost of shipping for this order. Total cost of processing fees for this order. Total amount of credit applied to this order. Total cost of the products, shipping, and processing fees in this order. Total tax for this order. Total cost of the products, shipping, processing fees, tax, and global shipping costs in this order. Total cost of global shipping for this order through the Global Relay service. Only provided when calling the /orders/:id endpoint. ISO 8601 When the recipient was notified of the order. For gifts, when the recipient opened the order. For gifts, when the recipient accepted the order. When the order entered pending payment status. When the order was paid for. When the order was first shipped. If there are multiple shipments, this is when the first shipment shipped. When the order was delivered. If there are multiple shipments, this is when all shipments were delivered. If this order is a gift that was swapped, this displays the original cart that was sent to the recipient. The brand that this product is from. If this order is a gift that was swapped, this displays the original amounts of the cart that was sent to the recipient. The Goody user who sent this order. 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). The reference ID displayed on receipts and other locations as the ID for this order. # Event: order.gift_opened Emitted when a gift is first opened. Note that if you open the gift link yourself, you might trigger this event. ## Example ```json { "event_type": "order.gift_opened", "id": "ad097c47-bf12-45c9-8feb-0536a0012c09", "data": { "id": "10c588dd-d566-45bf-86e9-c23bd1f1587b", "status": "opened", "individual_gift_link": "https://gifts.ongoody.com/gift/vWtUe8lQRJuoyYzKlYeHMkbV", "recipient_first_name": "Alena", "recipient_last_name": "Kenter", "recipient_email": "alena@ongoody.com", "card_id": "ae4cb4ce-75fc-4782-a9ab-2f30d9b7b41d", "message": "Thank you!", "thank_you_note": null, "view_count_recipient": 0, "is_swapped": false, "order_batch_id": "4133078a-c35f-441e-8e92-57645342b299", "expires_at": null, "cart": { "id": "39b04e91-6a40-468d-8ed4-f59e9059afae", "items": [ { "id": "d59dead0-a44c-44df-885f-030612038a48", "quantity": 1, "product": { "id": "c399bafb-3fbc-40c5-bef3-9158b7a19abc", "name": "Cookies", "brand": { "id": "db631527-c59c-409c-823f-42a24c972283", "name": "Cookie Company" } } } ] }, "shipments": [], "amounts": { "amount_product": 1000, "amount_shipping": 1000, "amount_processing_fee": 100, "amount_pre_tax_total": 2100, "amount_tax": null, "amount_total": null, "amount_global_relay_cost": null }, "sender": { "first_name": "Test", "last_name": "User", "email": "15556038009@test.ongoody.com" }, "workspace_id": "8779bb01-ca47-4e9e-a845-d05f509c4be3", "workspace_name": "Test Team", "original_cart": null, "original_amounts": null, "reference_id": "PCI7GLZ3KFIEN8MWWSD5LDCF" } } ``` ## Schema The type of event that occurred The unique ID for this event An individual order contains the gift link to be sent to the recipient (if applicable) and other information about the order. Allowed values: `created` `notified` `opened` `accepted` `pending_payment` `paid` `ordered` `shipped` `delivered` `failed` `canceled` 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. 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). The brand that this product is from. A list of the shipments for the order. Allowed values: `pending` `tracking` `shipped` `delivered` `delivered_override` `failed` `failed_unset_tracking` `failed_with_reship` The name of the brand that this shipment is from The carrier for this shipment, e.g. UPS. Only for approved distribution partners. ISO 8601 ISO 8601 The estimated delivery time of this shipment. Organizations are sub-divided into workspaces. Orders are contained in workspaces, identified by this ID. For gifts, the date and time the gift is set to expire. The digital greeting card on this gift. The message in this gift, provided by the sender. A thank you note sent by the recipient. The number of times the recipient viewed the gift. 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`. On Goody for Business, all orders are attached to a order batch, which is a collection of one or more orders. Costs in USD cents (i.e. \$1.00 = 100). If the order was swapped, `amounts` displays the most recent amounts (i.e. post-swap). Total cost of the products in this order. Total cost of shipping for this order. Total cost of processing fees for this order. Total amount of credit applied to this order. Total cost of the products, shipping, and processing fees in this order. Total tax for this order. Total cost of the products, shipping, processing fees, tax, and global shipping costs in this order. Total cost of global shipping for this order through the Global Relay service. Only provided when calling the /orders/:id endpoint. ISO 8601 When the recipient was notified of the order. For gifts, when the recipient opened the order. For gifts, when the recipient accepted the order. When the order entered pending payment status. When the order was paid for. When the order was first shipped. If there are multiple shipments, this is when the first shipment shipped. When the order was delivered. If there are multiple shipments, this is when all shipments were delivered. If this order is a gift that was swapped, this displays the original cart that was sent to the recipient. The brand that this product is from. If this order is a gift that was swapped, this displays the original amounts of the cart that was sent to the recipient. The Goody user who sent this order. The reference ID displayed on receipts and other locations as the ID for this order. # Event: order.refunded Emitted when an order has been refunded. ## Example ```json { "event_type": "order.refunded", "id": "ad097c47-bf12-45c9-8feb-0536a0012c09", "data": { "id": "8999f804-d731-440d-a67d-35444c12c493", "status": "shipped", "individual_gift_link": "https://gifts.ongoody.com/gift/IsDyQQWtqrOyGPgZ9bVm6ptz", "recipient_first_name": "Alena", "recipient_last_name": "Kenter", "recipient_email": "alena@ongoody.com", "card_id": "7e79fd96-212b-4468-9989-57b896ca22f4", "message": "Thank you!", "thank_you_note": null, "view_count_recipient": 0, "is_swapped": false, "order_batch_id": "d158184c-6b31-4a72-b39f-8f8ca04ecbdd", "expires_at": null, "cart": { "id": "3ff7dab1-ae03-4b20-a2c8-82a3f3326b83", "items": [ { "id": "284dc74f-a2c4-4b62-bfe5-94c464d56ea7", "quantity": 1, "product": { "id": "10227d72-c355-4881-8007-aad34f501055", "name": "Cookies", "brand": { "id": "fe370ec6-1208-4d23-b936-de857ceeae6d", "name": "Cookie Company" } } } ] }, "shipments": [], "amounts": { "amount_product": 1000, "amount_shipping": 1000, "amount_processing_fee": 100, "amount_pre_tax_total": 2100, "amount_tax": 150, "amount_total": 2250, "amount_global_relay_cost": null }, "sender": { "first_name": "Test", "last_name": "User", "email": "15551494889@test.ongoody.com" }, "workspace_id": "dfe0d5cb-2c98-4800-a950-b40cca509250", "workspace_name": "Test Team", "original_cart": null, "original_amounts": null, "reference_id": "2MUPN0YMGIDT7TJNPPFPB7WE" } } ``` ## Schema The type of event that occurred The unique ID for this event An individual order contains the gift link to be sent to the recipient (if applicable) and other information about the order. Allowed values: `created` `notified` `opened` `accepted` `pending_payment` `paid` `ordered` `shipped` `delivered` `failed` `canceled` 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. 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). The brand that this product is from. A list of the shipments for the order. Allowed values: `pending` `tracking` `shipped` `delivered` `delivered_override` `failed` `failed_unset_tracking` `failed_with_reship` The name of the brand that this shipment is from The carrier for this shipment, e.g. UPS. Only for approved distribution partners. ISO 8601 ISO 8601 The estimated delivery time of this shipment. Organizations are sub-divided into workspaces. Orders are contained in workspaces, identified by this ID. For gifts, the date and time the gift is set to expire. The digital greeting card on this gift. The message in this gift, provided by the sender. A thank you note sent by the recipient. The number of times the recipient viewed the gift. 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`. On Goody for Business, all orders are attached to a order batch, which is a collection of one or more orders. Costs in USD cents (i.e. \$1.00 = 100). If the order was swapped, `amounts` displays the most recent amounts (i.e. post-swap). Total cost of the products in this order. Total cost of shipping for this order. Total cost of processing fees for this order. Total amount of credit applied to this order. Total cost of the products, shipping, and processing fees in this order. Total tax for this order. Total cost of the products, shipping, processing fees, tax, and global shipping costs in this order. Total cost of global shipping for this order through the Global Relay service. Only provided when calling the /orders/:id endpoint. ISO 8601 When the recipient was notified of the order. For gifts, when the recipient opened the order. For gifts, when the recipient accepted the order. When the order entered pending payment status. When the order was paid for. When the order was first shipped. If there are multiple shipments, this is when the first shipment shipped. When the order was delivered. If there are multiple shipments, this is when all shipments were delivered. If this order is a gift that was swapped, this displays the original cart that was sent to the recipient. The brand that this product is from. If this order is a gift that was swapped, this displays the original amounts of the cart that was sent to the recipient. The Goody user who sent this order. The reference ID displayed on receipts and other locations as the ID for this order. # Event: order.shipped Emitted when the order is shipped. If there are multiple shipments, this is emitted when the first shipment for this order is in transit. You can access the list of shipments under the `shipments` field. Note that for multi-shipment orders, when this order first enters the shipped state, the list of shipments might be incomplete since more shipments might be shipped later. ## Example ```json { "event_type": "order.shipped", "id": "ad097c47-bf12-45c9-8feb-0536a0012c09", "data": { "id": "10c588dd-d566-45bf-86e9-c23bd1f1587b", "status": "shipped", "individual_gift_link": "https://gifts.ongoody.com/gift/vWtUe8lQRJuoyYzKlYeHMkbV", "recipient_first_name": "Alena", "recipient_last_name": "Kenter", "recipient_email": "alena@ongoody.com", "card_id": "ae4cb4ce-75fc-4782-a9ab-2f30d9b7b41d", "message": "Thank you!", "thank_you_note": null, "view_count_recipient": 0, "is_swapped": false, "order_batch_id": "4133078a-c35f-441e-8e92-57645342b299", "expires_at": null, "cart": { "id": "39b04e91-6a40-468d-8ed4-f59e9059afae", "items": [ { "id": "d59dead0-a44c-44df-885f-030612038a48", "quantity": 1, "product": { "id": "c399bafb-3fbc-40c5-bef3-9158b7a19abc", "name": "Cookies", "brand": { "id": "db631527-c59c-409c-823f-42a24c972283", "name": "Cookie Company" } } } ] }, "shipments": [ { "id": "9a1a2003-bb03-4409-b7fd-243b2e600e46", "status": "shipped", "brand_name": "Cookie Company", "tracking_carrier": "UPS", "shipped_at": "2023-01-23T00:00:00Z", "delivered_at": null, "delivery_eta": "2023-01-26T00:00:00Z" } ], "amounts": { "amount_product": 1000, "amount_shipping": 1000, "amount_processing_fee": 100, "amount_pre_tax_total": 2100, "amount_tax": 150, "amount_total": 2250, "amount_global_relay_cost": null }, "sender": { "first_name": "Test", "last_name": "User", "email": "15556038009@test.ongoody.com" }, "workspace_id": "8779bb01-ca47-4e9e-a845-d05f509c4be3", "workspace_name": "Test Team", "original_cart": null, "original_amounts": null, "reference_id": "PCI7GLZ3KFIEN8MWWSD5LDCF" } } ``` ## Schema The type of event that occurred The unique ID for this event An individual order contains the gift link to be sent to the recipient (if applicable) and other information about the order. Allowed values: `created` `notified` `opened` `accepted` `pending_payment` `paid` `ordered` `shipped` `delivered` `failed` `canceled` 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. 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). The brand that this product is from. A list of the shipments for the order. Allowed values: `pending` `tracking` `shipped` `delivered` `delivered_override` `failed` `failed_unset_tracking` `failed_with_reship` The name of the brand that this shipment is from The carrier for this shipment, e.g. UPS. Only for approved distribution partners. ISO 8601 ISO 8601 The estimated delivery time of this shipment. Organizations are sub-divided into workspaces. Orders are contained in workspaces, identified by this ID. For gifts, the date and time the gift is set to expire. The digital greeting card on this gift. The message in this gift, provided by the sender. A thank you note sent by the recipient. The number of times the recipient viewed the gift. 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`. On Goody for Business, all orders are attached to a order batch, which is a collection of one or more orders. Costs in USD cents (i.e. \$1.00 = 100). If the order was swapped, `amounts` displays the most recent amounts (i.e. post-swap). Total cost of the products in this order. Total cost of shipping for this order. Total cost of processing fees for this order. Total amount of credit applied to this order. Total cost of the products, shipping, and processing fees in this order. Total tax for this order. Total cost of the products, shipping, processing fees, tax, and global shipping costs in this order. Total cost of global shipping for this order through the Global Relay service. Only provided when calling the /orders/:id endpoint. ISO 8601 When the recipient was notified of the order. For gifts, when the recipient opened the order. For gifts, when the recipient accepted the order. When the order entered pending payment status. When the order was paid for. When the order was first shipped. If there are multiple shipments, this is when the first shipment shipped. When the order was delivered. If there are multiple shipments, this is when all shipments were delivered. If this order is a gift that was swapped, this displays the original cart that was sent to the recipient. The brand that this product is from. If this order is a gift that was swapped, this displays the original amounts of the cart that was sent to the recipient. The Goody user who sent this order. The reference ID displayed on receipts and other locations as the ID for this order. # Event: order.thank_you_note_added Emitted when the recipient adds a thank you note to a gift. This typically happens shortly after the gift has been accepted, but can happen anytime after acceptance. You can access the thank you note on the `thank_you_note` property of the order. ## Example ```json { "event_type": "order.thank_you_note_added", "id": "ad097c47-bf12-45c9-8feb-0536a0012c09", "data": { "id": "10c588dd-d566-45bf-86e9-c23bd1f1587b", "status": "accepted", "individual_gift_link": "https://gifts.ongoody.com/gift/vWtUe8lQRJuoyYzKlYeHMkbV", "recipient_first_name": "Alena", "recipient_last_name": "Kenter", "recipient_email": "alena@ongoody.com", "card_id": "ae4cb4ce-75fc-4782-a9ab-2f30d9b7b41d", "message": "Thank you!", "thank_you_note": "Thanks for the gift!", "view_count_recipient": 0, "is_swapped": false, "order_batch_id": "4133078a-c35f-441e-8e92-57645342b299", "expires_at": null, "cart": { "id": "39b04e91-6a40-468d-8ed4-f59e9059afae", "items": [ { "id": "d59dead0-a44c-44df-885f-030612038a48", "quantity": 1, "product": { "id": "c399bafb-3fbc-40c5-bef3-9158b7a19abc", "name": "Cookies", "brand": { "id": "db631527-c59c-409c-823f-42a24c972283", "name": "Cookie Company" } } } ] }, "shipments": [], "amounts": { "amount_product": 1000, "amount_shipping": 1000, "amount_processing_fee": 100, "amount_pre_tax_total": 2100, "amount_tax": 150, "amount_total": 2250, "amount_global_relay_cost": null }, "sender": { "first_name": "Test", "last_name": "User", "email": "15556038009@test.ongoody.com" }, "workspace_id": "8779bb01-ca47-4e9e-a845-d05f509c4be3", "workspace_name": "Test Team", "original_cart": null, "original_amounts": null, "reference_id": "PCI7GLZ3KFIEN8MWWSD5LDCF" } } ``` ## Schema The type of event that occurred The unique ID for this event An individual order contains the gift link to be sent to the recipient (if applicable) and other information about the order. Allowed values: `created` `notified` `opened` `accepted` `pending_payment` `paid` `ordered` `shipped` `delivered` `failed` `canceled` 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. 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). The brand that this product is from. A list of the shipments for the order. Allowed values: `pending` `tracking` `shipped` `delivered` `delivered_override` `failed` `failed_unset_tracking` `failed_with_reship` The name of the brand that this shipment is from The carrier for this shipment, e.g. UPS. Only for approved distribution partners. ISO 8601 ISO 8601 The estimated delivery time of this shipment. Organizations are sub-divided into workspaces. Orders are contained in workspaces, identified by this ID. For gifts, the date and time the gift is set to expire. The digital greeting card on this gift. The message in this gift, provided by the sender. A thank you note sent by the recipient. The number of times the recipient viewed the gift. 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`. On Goody for Business, all orders are attached to a order batch, which is a collection of one or more orders. Costs in USD cents (i.e. \$1.00 = 100). If the order was swapped, `amounts` displays the most recent amounts (i.e. post-swap). Total cost of the products in this order. Total cost of shipping for this order. Total cost of processing fees for this order. Total amount of credit applied to this order. Total cost of the products, shipping, and processing fees in this order. Total tax for this order. Total cost of the products, shipping, processing fees, tax, and global shipping costs in this order. Total cost of global shipping for this order through the Global Relay service. Only provided when calling the /orders/:id endpoint. ISO 8601 When the recipient was notified of the order. For gifts, when the recipient opened the order. For gifts, when the recipient accepted the order. When the order entered pending payment status. When the order was paid for. When the order was first shipped. If there are multiple shipments, this is when the first shipment shipped. When the order was delivered. If there are multiple shipments, this is when all shipments were delivered. If this order is a gift that was swapped, this displays the original cart that was sent to the recipient. The brand that this product is from. If this order is a gift that was swapped, this displays the original amounts of the cart that was sent to the recipient. The Goody user who sent this order. The reference ID displayed on receipts and other locations as the ID for this order. # Event: order_batch.completed Emitted when an order batch is fully processed, which is when all orders are created for each recipient in the order batch. **For non-scheduled order batches,** the `order_batch.completed` event is emitted immediately after the order batch is finished processing and all orders have been created. *(This is instantly after the `order_batch.created` webhook event for order batches with 10 or fewer recipients, and shortly after the `order_batch.created` event for order batches with more than 10 recipients.)* **For scheduled order batches,** the `order_batch.completed` event is emitted when the order batch scheduled time is reached, and orders are created for the order batch. ## Example ```json { "event_type": "gift_batch.completed", "id": "ad097c47-bf12-45c9-8feb-0536a0012c09", "data": { "id": "bd1fd5b5-6339-4331-a404-66200143ff0f", "send_status": "complete", "from_name": "John", "message": "Thank you!", "gifts_count": 2, "gifts_preview": [ { "id": "1f6e253e-4d03-4a85-a349-0659384ac894", "status": "created", "recipient_first_name": "Alena", "recipient_last_name": "Kenter", "recipient_email": "alena@ongoody.com", "individual_gift_link_shared": "https://gifts.ongoody.com/gift/Anc0HT0ZhyKAJguP75jt2Rar", "card_id": "60c4a674-4f0e-4031-9eca-645d34bb6cec", "message": "Thank you!", "thank_you_note": null, "view_count_recipient": 0, "is_swapped": false, "gift_batch_id": "bd1fd5b5-6339-4331-a404-66200143ff0f", "cart": { "id": "e0597695-5e19-4bbc-9a99-0fd540a9e68f", "items": [ { "id": "5f4e70e9-5cc7-406e-8058-c513af667511", "quantity": 1, "product": { "id": "e69ea31a-320f-48f5-8fd7-0692df22328e", "name": "Cookies", "brand": { "id": "393d847d-874b-4338-b834-fe3e0cf27644", "name": "Cookie Company" } } } ] }, "shipments": [], "amounts": { "amount_product": 1000, "amount_shipping": 1000, "amount_processing_fee": 100, "amount_pre_tax_total": 2100, "amount_tax": null, "amount_total": null, "amount_global_relay_cost": null }, "sender": { "first_name": "Test", "last_name": "User", "email": "15550197216@test.ongoody.com" }, "workspace_id": "ae6e2795-8667-4d21-a1b0-fe7f642d7893", "workspace_name": "Test Team", "original_cart": null, "original_amounts": null, "reference_id": "LLRMPDGSSD7GXISGMACUKUIS" }, { "id": "981c4abd-1f0c-4287-8c35-c7cea8f6f5da", "status": "created", "recipient_first_name": "Michael", "recipient_last_name": "Franci", "recipient_email": "michael@ongoody.com", "individual_gift_link_shared": "https://gifts.ongoody.com/gift/6p5k63B9ym4ksusHG6hr6xtA", "card_id": "60c4a674-4f0e-4031-9eca-645d34bb6cec", "message": "Thank you!", "thank_you_note": null, "view_count_recipient": 0, "is_swapped": false, "gift_batch_id": "bd1fd5b5-6339-4331-a404-66200143ff0f", "cart": { "id": "e0597695-5e19-4bbc-9a99-0fd540a9e68f", "items": [ { "id": "5f4e70e9-5cc7-406e-8058-c513af667511", "quantity": 1, "product": { "id": "e69ea31a-320f-48f5-8fd7-0692df22328e", "name": "Cookies", "brand": { "id": "393d847d-874b-4338-b834-fe3e0cf27644", "name": "Cookie Company" } } } ] }, "shipments": [], "amounts": { "amount_product": 1000, "amount_shipping": 1000, "amount_processing_fee": 100, "amount_pre_tax_total": 2100, "amount_tax": null, "amount_total": null, "amount_global_relay_cost": null }, "sender": { "first_name": "Test", "last_name": "User", "email": "15550197216@test.ongoody.com" }, "workspace_id": "ae6e2795-8667-4d21-a1b0-fe7f642d7893", "workspace_name": "Test Team", "original_cart": null, "original_amounts": null, "reference_id": "U23DXZIHYSI4U9M8SBQ7XMVH" } ], "recipients_count": 2, "recipients_preview": [ { "first_name": "Alena", "last_name": "Kenter", "email": "alena@ongoody.com" }, { "first_name": "Michael", "last_name": "Franci", "email": "michael@ongoody.com" } ], "cart": { "id": "e0597695-5e19-4bbc-9a99-0fd540a9e68f", "items": [ { "id": "5f4e70e9-5cc7-406e-8058-c513af667511", "quantity": 1, "product": { "id": "e69ea31a-320f-48f5-8fd7-0692df22328e", "name": "Cookies", "brand": { "id": "393d847d-874b-4338-b834-fe3e0cf27644", "name": "Cookie Company" } } } ] }, "is_scheduled_send": false, "scheduled_send_on": null, "expires_at": null, "send_method": "link_multiple_custom_list", "batch_name": "Alena Kenter and Michael Franci", "card_id": "60c4a674-4f0e-4031-9eca-645d34bb6cec", "sender": { "first_name": "Test", "last_name": "User", "email": "15550197216@test.ongoody.com" }, "workspace_id": "ae6e2795-8667-4d21-a1b0-fe7f642d7893", "workspace_name": "Test Team", "reference_id": "61Q2FSAHYYISJRZDHQXGYTBU" } } ``` ## Schema The type of event that occurred The unique ID for this event An order batch is the primary resource created by the API. Order batches contain an array of orders. An order batch is the primary resource created by the API. Order batches contain an array of orders. The `pending` status indicates that an order batch is being prepared to be sent out. If it is not scheduled, it is being sent asynchronously. If it is scheduled, it will stay in `pending` state until the scheduled time is reached, at which point it will be processed and moved to `complete`. When it is in `pending` status, no orders are created yet. When the order batch is in `complete` status, all orders are created and available. Allowed values: `pending` `complete` `failed` `canceled` The name of the sender. This is displayed on the order and notifications. The message in this order batch, provided by the sender. The total number of orders in this order batch. This might be blank if the order batch is scheduled for the future, or it could be fewer than the recipient count if the order batch is in the process of being sent. A preview of the first 10 orders in this order batch. To paginate through all of the orders, use the `/order_batches/:id/orders` endpoint with `?page&per_page`. If your use case never sends more than 10 orders in a single batch, you can use this field instead of calling `/order_batches/:id/orders`. For order batches with more than 10 recipients, this array will be empty while the orders are asynchronously created in the background. Allowed values: `created` `notified` `opened` `accepted` `pending_payment` `paid` `ordered` `shipped` `delivered` `failed` `canceled` 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. 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). The brand that this product is from. A list of the shipments for the order. Allowed values: `pending` `tracking` `shipped` `delivered` `delivered_override` `failed` `failed_unset_tracking` `failed_with_reship` The name of the brand that this shipment is from The carrier for this shipment, e.g. UPS. Only for approved distribution partners. ISO 8601 ISO 8601 The estimated delivery time of this shipment. Organizations are sub-divided into workspaces. Orders are contained in workspaces, identified by this ID. For gifts, the date and time the gift is set to expire. The digital greeting card on this gift. The message in this gift, provided by the sender. A thank you note sent by the recipient. The number of times the recipient viewed the gift. 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`. On Goody for Business, all orders are attached to a order batch, which is a collection of one or more orders. Costs in USD cents (i.e. \$1.00 = 100). If the order was swapped, `amounts` displays the most recent amounts (i.e. post-swap). Total cost of the products in this order. Total cost of shipping for this order. Total cost of processing fees for this order. Total amount of credit applied to this order. Total cost of the products, shipping, and processing fees in this order. Total tax for this order. Total cost of the products, shipping, processing fees, tax, and global shipping costs in this order. Total cost of global shipping for this order through the Global Relay service. Only provided when calling the /orders/:id endpoint. ISO 8601 When the recipient was notified of the order. For gifts, when the recipient opened the order. For gifts, when the recipient accepted the order. When the order entered pending payment status. When the order was paid for. When the order was first shipped. If there are multiple shipments, this is when the first shipment shipped. When the order was delivered. If there are multiple shipments, this is when all shipments were delivered. If this order is a gift that was swapped, this displays the original cart that was sent to the recipient. The brand that this product is from. If this order is a gift that was swapped, this displays the original amounts of the cart that was sent to the recipient. The Goody user who sent this order. The reference ID displayed on receipts and other locations as the ID for this order. The total number of recipients in this order batch. A preview of the first 10 recipients in this order batch. To see all of the recipients, use `/order_batches/:id/recipients`. Recipients contain the original contact information provided for each recipient when the order batch was created. The cart that was sent for this order batch. This is the original cart that was created for this order batch. If individual orders were swapped, this still remains the same, whereas orders' `cart` would change if they were swapped. Whether this order batch was set up as a scheduled send. This stays as `true` after the scheduled send is complete. To determine if the order batch is scheduled to be sent for the future, check if `status` is `pending` and `scheduled_send_on` is in the future. When a order batch is scheduled, orders are only created on the scheduled send date. The date and time the order batch is scheduled to be sent. This will be `null` if the order batch is not a scheduled send. This field remains after the scheduled send completes. ISO 8601, UTC. The date and time the order batch is set to expire. ISO 8601, UTC. The method for sending a order batch. Currently, the only supported send method is `link_multiple_custom_list` which specifies that a link should be created for each order, but no email should automatically be sent to the recipient. Allowed value: `link_multiple_custom_list` An internal name for the order batch, falling back to an auto-generated batch name. Not displayed to recipients. The digital greeting card on this order batch. The sender of the order batch. Organizations are sub-divided into workspaces. Order batches are contained in workspaces, identified by this ID. The reference ID displayed on receipts and other locations as the ID for this order batch. # null Emitted when a order batch is created in the organization. **For non-scheduled order batches,** for order batches with 10 or fewer recipients, the `order_batch.created` event will contain all of the orders for each recipient. For order batches with more than 10 recipients, order creation happens asynchronously, and the `order_batch.completed` event is emitted immediately after the orders are created. **For scheduled order batches,** no order will be created when the order batch is created until the scheduled send time. The `order_batch.completed` event is emitted when the order batch scheduled time is reached, and orders are created for the order batch. ## Example ```json { "event_type": "gift_batch.created", "id": "ad097c47-bf12-45c9-8feb-0536a0012c09", "data": { "id": "bd1fd5b5-6339-4331-a404-66200143ff0f", "send_status": "complete", "from_name": "John", "message": "Thank you!", "gifts_count": 2, "gifts_preview": [ { "id": "1f6e253e-4d03-4a85-a349-0659384ac894", "status": "created", "recipient_first_name": "Alena", "recipient_last_name": "Kenter", "recipient_email": "alena@ongoody.com", "individual_gift_link_shared": "https://gifts.ongoody.com/gift/Anc0HT0ZhyKAJguP75jt2Rar", "card_id": "60c4a674-4f0e-4031-9eca-645d34bb6cec", "message": "Thank you!", "thank_you_note": null, "view_count_recipient": 0, "is_swapped": false, "gift_batch_id": "bd1fd5b5-6339-4331-a404-66200143ff0f", "cart": { "id": "e0597695-5e19-4bbc-9a99-0fd540a9e68f", "items": [ { "id": "5f4e70e9-5cc7-406e-8058-c513af667511", "quantity": 1, "product": { "id": "e69ea31a-320f-48f5-8fd7-0692df22328e", "name": "Cookies", "brand": { "id": "393d847d-874b-4338-b834-fe3e0cf27644", "name": "Cookie Company" } } } ] }, "shipments": [], "amounts": { "amount_product": 1000, "amount_shipping": 1000, "amount_processing_fee": 100, "amount_pre_tax_total": 2100, "amount_tax": null, "amount_total": null, "amount_global_relay_cost": null }, "sender": { "first_name": "Test", "last_name": "User", "email": "15550197216@test.ongoody.com" }, "workspace_id": "ae6e2795-8667-4d21-a1b0-fe7f642d7893", "workspace_name": "Test Team", "original_cart": null, "original_amounts": null, "reference_id": "LLRMPDGSSD7GXISGMACUKUIS" }, { "id": "981c4abd-1f0c-4287-8c35-c7cea8f6f5da", "status": "created", "recipient_first_name": "Michael", "recipient_last_name": "Franci", "recipient_email": "michael@ongoody.com", "individual_gift_link_shared": "https://gifts.ongoody.com/gift/6p5k63B9ym4ksusHG6hr6xtA", "card_id": "60c4a674-4f0e-4031-9eca-645d34bb6cec", "message": "Thank you!", "thank_you_note": null, "view_count_recipient": 0, "is_swapped": false, "gift_batch_id": "bd1fd5b5-6339-4331-a404-66200143ff0f", "cart": { "id": "e0597695-5e19-4bbc-9a99-0fd540a9e68f", "items": [ { "id": "5f4e70e9-5cc7-406e-8058-c513af667511", "quantity": 1, "product": { "id": "e69ea31a-320f-48f5-8fd7-0692df22328e", "name": "Cookies", "brand": { "id": "393d847d-874b-4338-b834-fe3e0cf27644", "name": "Cookie Company" } } } ] }, "shipments": [], "amounts": { "amount_product": 1000, "amount_shipping": 1000, "amount_processing_fee": 100, "amount_pre_tax_total": 2100, "amount_tax": null, "amount_total": null, "amount_global_relay_cost": null }, "sender": { "first_name": "Test", "last_name": "User", "email": "15550197216@test.ongoody.com" }, "workspace_id": "ae6e2795-8667-4d21-a1b0-fe7f642d7893", "workspace_name": "Test Team", "original_cart": null, "original_amounts": null, "reference_id": "U23DXZIHYSI4U9M8SBQ7XMVH" } ], "recipients_count": 2, "recipients_preview": [ { "first_name": "Alena", "last_name": "Kenter", "email": "alena@ongoody.com" }, { "first_name": "Michael", "last_name": "Franci", "email": "michael@ongoody.com" } ], "cart": { "id": "e0597695-5e19-4bbc-9a99-0fd540a9e68f", "items": [ { "id": "5f4e70e9-5cc7-406e-8058-c513af667511", "quantity": 1, "product": { "id": "e69ea31a-320f-48f5-8fd7-0692df22328e", "name": "Cookies", "brand": { "id": "393d847d-874b-4338-b834-fe3e0cf27644", "name": "Cookie Company" } } } ] }, "is_scheduled_send": false, "scheduled_send_on": null, "expires_at": null, "send_method": "link_multiple_custom_list", "batch_name": "Alena Kenter and Michael Franci", "card_id": "60c4a674-4f0e-4031-9eca-645d34bb6cec", "sender": { "first_name": "Test", "last_name": "User", "email": "15550197216@test.ongoody.com" }, "workspace_id": "ae6e2795-8667-4d21-a1b0-fe7f642d7893", "workspace_name": "Test Team", "reference_id": "61Q2FSAHYYISJRZDHQXGYTBU" } } ``` ## Schema The type of event that occurred The unique ID for this event An order batch is the primary resource created by the API. Order batches contain an array of orders. The `pending` status indicates that an order batch is being prepared to be sent out. If it is not scheduled, it is being sent asynchronously. If it is scheduled, it will stay in `pending` state until the scheduled time is reached, at which point it will be processed and moved to `complete`. When it is in `pending` status, no orders are created yet. When the order batch is in `complete` status, all orders are created and available. Allowed values: `pending` `complete` `failed` `canceled` The name of the sender. This is displayed on the order and notifications. The message in this order batch, provided by the sender. The total number of orders in this order batch. This might be blank if the order batch is scheduled for the future, or it could be fewer than the recipient count if the order batch is in the process of being sent. A preview of the first 10 orders in this order batch. To paginate through all of the orders, use the `/order_batches/:id/orders` endpoint with `?page&per_page`. If your use case never sends more than 10 orders in a single batch, you can use this field instead of calling `/order_batches/:id/orders`. For order batches with more than 10 recipients, this array will be empty while the orders are asynchronously created in the background. Allowed values: `created` `notified` `opened` `accepted` `pending_payment` `paid` `ordered` `shipped` `delivered` `failed` `canceled` 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. 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). The brand that this product is from. A list of the shipments for the order. Allowed values: `pending` `tracking` `shipped` `delivered` `delivered_override` `failed` `failed_unset_tracking` `failed_with_reship` The name of the brand that this shipment is from The carrier for this shipment, e.g. UPS. Only for approved distribution partners. ISO 8601 ISO 8601 The estimated delivery time of this shipment. Organizations are sub-divided into workspaces. Orders are contained in workspaces, identified by this ID. For gifts, the date and time the gift is set to expire. The digital greeting card on this gift. The message in this gift, provided by the sender. A thank you note sent by the recipient. The number of times the recipient viewed the gift. 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`. On Goody for Business, all orders are attached to a order batch, which is a collection of one or more orders. Costs in USD cents (i.e. \$1.00 = 100). If the order was swapped, `amounts` displays the most recent amounts (i.e. post-swap). Total cost of the products in this order. Total cost of shipping for this order. Total cost of processing fees for this order. Total amount of credit applied to this order. Total cost of the products, shipping, and processing fees in this order. Total tax for this order. Total cost of the products, shipping, processing fees, tax, and global shipping costs in this order. Total cost of global shipping for this order through the Global Relay service. Only provided when calling the /orders/:id endpoint. ISO 8601 When the recipient was notified of the order. For gifts, when the recipient opened the order. For gifts, when the recipient accepted the order. When the order entered pending payment status. When the order was paid for. When the order was first shipped. If there are multiple shipments, this is when the first shipment shipped. When the order was delivered. If there are multiple shipments, this is when all shipments were delivered. If this order is a gift that was swapped, this displays the original cart that was sent to the recipient. The brand that this product is from. If this order is a gift that was swapped, this displays the original amounts of the cart that was sent to the recipient. The Goody user who sent this order. The reference ID displayed on receipts and other locations as the ID for this order. The total number of recipients in this order batch. A preview of the first 10 recipients in this order batch. To see all of the recipients, use `/order_batches/:id/recipients`. Recipients contain the original contact information provided for each recipient when the order batch was created. The cart that was sent for this order batch. This is the original cart that was created for this order batch. If individual orders were swapped, this still remains the same, whereas orders' `cart` would change if they were swapped. Whether this order batch was set up as a scheduled send. This stays as `true` after the scheduled send is complete. To determine if the order batch is scheduled to be sent for the future, check if `status` is `pending` and `scheduled_send_on` is in the future. When a order batch is scheduled, orders are only created on the scheduled send date. The date and time the order batch is scheduled to be sent. This will be `null` if the order batch is not a scheduled send. This field remains after the scheduled send completes. ISO 8601, UTC. The date and time the order batch is set to expire. ISO 8601, UTC. The method for sending a order batch. Currently, the only supported send method is `link_multiple_custom_list` which specifies that a link should be created for each order, but no email should automatically be sent to the recipient. Allowed value: `link_multiple_custom_list` An internal name for the order batch, falling back to an auto-generated batch name. Not displayed to recipients. The digital greeting card on this order batch. The sender of the order batch. Organizations are sub-divided into workspaces. Order batches are contained in workspaces, identified by this ID. The reference ID displayed on receipts and other locations as the ID for this order batch. # Webhooks Webhooks allow you to be notified when events happen on Goody orders and order batches. You can subscribe to all webhooks, or a subset of them. Webhooks are sent by the Svix platform. For the complete guide to webhooks, visit the Webhooks page for the API you are using: ## Available webhooks | Webhook | Description | | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | **[order\_batch.created](/webhooks/events/order_batch.created)** | When an order batch is newly created. The order batch could still be in process of sending, or scheduled for the future. | | **[order\_batch.completed](/webhooks/events/order_batch.completed)** | When an order batch is fully processed and all orders have been created. | | **[order.created](/webhooks/events/order.created)** | When an order is created and is ready to be opened. | | **[order.gift\_opened](/webhooks/events/order.gift_opened)** | When a gift is opened by the recipient. | | **[order.gift\_accepted](/webhooks/events/order.gift_accepted)** | When a gift has been accepted by the recipient. | | **[order.thank\_you\_note\_added](/webhooks/events/order.thank_you_note_added)** | When a recipient adds a thank you note to a order after accepting it. | | **[order.shipped](/webhooks/events/order.shipped)** | When an order starts shipping. If there are multiple shipments, this is called for the first. | | **[order.delivered](/webhooks/events/order.delivered)** | When an order is fully delivered. If there are multiple shipments, this is called when all shipments are delivered. | | **[order.canceled](/webhooks/events/order.canceled)** | When an order has been canceled. | | **[order.refunded](/webhooks/events/order.refunded)** | When an order has been refunded. | ## Setting up a new webhook ![](https://mintlify.s3.us-west-1.amazonaws.com/goody/images/new-webhooks.png) Enter a URL to recieve webhooks in the **Endpoint URL** section. You can leave **Message Filtering** blank to receive all events, or select specific events to receive. ## Webhook security To ensure the integrity of the webhooks you receive, we recommend verifying the signatures of the webhooks you receive. Svix provides packages for multiple languages that make verifying signatures easy. To see how, go to the [Webhook Security](/webhooks/webhook-security) page. ## Logs You can view the logs for webhook delivery for each endpoint, and re-send any failed webhooks if needed. ![webhook-logs.png](https://mintlify.s3.us-west-1.amazonaws.com/goody/images/logs.png) # Webhook security To ensure the integrity of the webhooks you receive, we recommend verifying the signatures of the webhooks you receive. The webhook platform we use, Svix, provides packages for multiple languages that make verifying signatures easy. ```JavaScript JavaScript npm install svix // Or yarn add svix ``` ```Python Python pip install svix ``` ```Ruby Ruby gem install svix ``` ```Rust Rust svix = "0" ``` ```Go Go go get github.com/svix/svix-webhooks/go ``` ```Java Java // Gradle implementation "com.svix:svix:0.x.y" // Maven com.svix svix 0.x.y ``` ```Kotlin Kotlin // Gradle implementation "com.svix.kotlin:svix-kotlin:0.x.y" // Maven com.svix.kotlin svix-kotlin 0.x.y ``` ```C# C# dotnet add package Svix ``` ```PHP PHP composer require svix/svix ``` First, obtain your webhook secret on the configuration page for your webhook under the **Signing Secret**: ![](https://mintlify.s3.us-west-1.amazonaws.com/goody/images/signing-secret.png) Then, to verify the webhook, pass your signing secret with the headers and raw payload body to the verify method. **Make sure to use the raw request body for the payload** If your framework parses JSON, you'll want to use the raw request body instead of the parsed JSON. ```JavaScript JavaScript import { Webhook } from "svix"; const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"; // These were all sent from the server const headers = { "svix-id": "msg_p5jXN8AQM9LWM0D4loKWxJek", "svix-timestamp": "1614265330", "svix-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=", }; const payload = '{"test": 2432232314}'; const wh = new Webhook(secret); // Throws on error, returns the verified content on success const payload = wh.verify(payload, headers); ``` ```Python Python from svix.webhooks import Webhook secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw" # These were all sent from the server headers = { "svix-id": "msg_p5jXN8AQM9LWM0D4loKWxJek", "svix-timestamp": "1614265330", "svix-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=", } payload = '{"test": 2432232314}' wh = Webhook(secret) # Throws on error, returns the verified content on success payload = wh.verify(payload, headers) ``` ```Ruby Ruby require 'svix' secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw" # These were all sent from the server headers = { "svix-id" => "msg_p5jXN8AQM9LWM0D4loKWxJek", "svix-timestamp" => "1614265330", "svix-signature" => "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=" } payload = '{"test": 2432232314}' wh = Svix::Webhook.new(secret) # Raises on error, returns the verified content on success json = wh.verify(payload, headers) ``` ```Rust Rust use svix::webhooks::Webhook; let secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw".to_string(); let mut headers = http::header::HeaderMap::new(); headers.insert("svix-id", "msg_p5jXN8AQM9LWM0D4loKWxJek"); headers.insert("svix-timestamp", "1614265330"); headers.insert("svix-signature", "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE="); let payload = b"{\"test\": 2432232314}"; let wh = Webhook::new(secret)?; wh.verify(&payload, &headers)?; // returns Ok on success, Err otherwise ``` ```Go Go import ( svix "github.com/svix/svix-webhooks/go" ) secret := "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw" // These were all sent from the server headers := http.Header{} headers.Set("svix-id", "msg_p5jXN8AQM9LWM0D4loKWxJek") headers.Set("svix-timestamp", "1614265330") headers.Set("svix-signature", "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=") payload := []byte(`{"test": 2432232314}`) wh, err := svix.NewWebhook(secret) err := wh.Verify(payload, headers) // returns nil on success, error otherwise ``` ```Java Java import com.svix.Webhook; String secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"; // These were all sent from the server HashMap> headerMap = new HashMap>(); headerMap.put("svix-id", Arrays.asList("msg_p5jXN8AQM9LWM0D4loKWxJek")); headerMap.put("svix-timestamp", Arrays.asList("1614265330")); headerMap.put("svix-signature", Arrays.asList("v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=")); HttpHeaders headers = HttpHeaders.of(headerMap, BiPredicate) String payload = "{\"test\": 2432232314}"; Webhook webhook = new Webhook(secret); webhook.verify(payload, headers) // throws WebhookVerificationError exception on failure. ``` ```Kotlin Kotlin import com.svix.kotlin.Webhook val secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"; // These were all sent from the server val headersMap = mapOf( "svix-id" to listOf("msg_p5jXN8AQM9LWM0D4loKWxJek"), "svix-timestamp" to listOf("1614265330"), "svix-signature" to listOf("v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=") ) val headers = HttpHeaders.of(headersMap) { _, _ -> true } val payload = "{\"test\": 2432232314}"; val webhook = Webhook(secret); webhook.verify(payload, headers) // throws WebhookVerificationError exception on failure. ``` ```C# C# using Svix; using System.Net; // These were all sent from the server var headers = new WebHeaderCollection(); headers.Set("svix-id", "msg_p5jXN8AQM9LWM0D4loKWxJek"); headers.Set("svix-timestamp", "1614265330"); headers.Set("svix-signature", "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE="); var payload = "{\"test\": 2432232314}"; var wh = new Webhook("whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw/Je4ZJEGP1QFb"); // Throws on error wh.Verify(payload, headers); ``` ```PHP PHP // import using composers autoload require_once('vendor/autoload.php'); // or manually require_once('/path/to/svix/php/init.php'); // These were all sent from the server $payload = '{"test": 2432232314}'; $header = array( 'svix-id' => 'msg_p5jXN8AQM9LWM0D4loKWxJek', 'svix-timestamp' => '1614265330', 'svix-signature' => 'v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=', ); // Throws on error, returns the verified content on success $wh = new \Svix\Webhook('whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw'); $json = $wh->verify($payload, $header); ``` To view more information on how to verify signatures, and to see examples for popular frameworks, visit [Svix's documentation](https://docs.svix.com/receiving/verifying-payloads/how). If you want to verify webhooks manually, [follow this guide](https://docs.svix.com/receiving/verifying-payloads/how-manual).