Create an order batch

POST

order_batches

object

from_name

string

message

string

recipients

array

cart

object

items

array

send_method

enum<string>

card_id

string

payment_method_id

string

workspace_id

string

scheduled_send_on

string

expires_at

string

swap

enum<string>

reserved_options

object

custom_price_tier

integer

curl --request POST \
  --url https://api.ongoody.com/v1/order_batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "from_name": "John",
  "message": "Thank you!",
  "send_method": "link_multiple_custom_list",
  "payment_method_id": null,
  "workspace_id": null,
  "card_id": "9f437d68-41a0-427d-ab87-e9330f4e045a",
  "recipients": [
    {
      "first_name": "Alena",
      "last_name": "Kenter",
      "email": "alena@ongoody.com"
    },
    {
      "first_name": "Michael",
      "last_name": "Franci",
      "email": "michael@ongoody.com"
    }
  ],
  "cart": {
    "items": [
      {
        "product_id": "5df75457-ba03-4dc6-97c1-42d977e28da1",
        "quantity": 1
      }
    ]
  }
}'

{
  "id": "67dc1ba7-e1d2-4670-9feb-ae2715ac2ef8",
  "send_status": "complete",
  "from_name": "John",
  "message": "Thank you!",
  "orders_count": 2,
  "orders_preview": [
    {
      "id": "f1ff395d-c255-4eeb-bd3c-92e74a5fa240",
      "status": "created",
      "individual_gift_link": "https://gifts.ongoody.com/gift/7XXHPrJtLTaH4ti8WVQWB0Vx",
      "recipient_first_name": "Alena",
      "recipient_last_name": "Kenter",
      "recipient_email": "alena@ongoody.com",
      "card_id": "9f437d68-41a0-427d-ab87-e9330f4e045a",
      "message": "Thank you!",
      "thank_you_note": null,
      "view_count_recipient": 0,
      "is_swapped": false,
      "order_batch_id": "67dc1ba7-e1d2-4670-9feb-ae2715ac2ef8",
      "expires_at": null,
      "cart": {
        "id": "0f50fb17-95c9-43e0-be6f-e3fb002672d7",
        "items": [
          {
            "id": "9119cd06-e239-4d76-9bb0-9c89504cc114",
            "quantity": 1,
            "product": {
              "id": "5df75457-ba03-4dc6-97c1-42d977e28da1",
              "name": "Cookies",
              "brand": {
                "id": "51244d3b-afef-44a6-a786-a5641621663d",
                "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": "15557150805@test.ongoody.com"
      },
      "workspace_id": "be6ba72a-7092-421a-8656-4b319b3816d5",
      "workspace_name": "Test Team",
      "original_cart": null,
      "original_amounts": null,
      "reference_id": "A7SWKYWQDLWLOWU6G8NAHR6V",
      "payment_link": null
    },
    {
      "id": "a3e85fc1-6dca-45b6-bf27-48168f888504",
      "status": "created",
      "individual_gift_link": "https://gifts.ongoody.com/gift/rwCoTg9lb7TEmLvSIe7yCdX3",
      "recipient_first_name": "Michael",
      "recipient_last_name": "Franci",
      "recipient_email": "michael@ongoody.com",
      "card_id": "9f437d68-41a0-427d-ab87-e9330f4e045a",
      "message": "Thank you!",
      "thank_you_note": null,
      "view_count_recipient": 0,
      "is_swapped": false,
      "order_batch_id": "67dc1ba7-e1d2-4670-9feb-ae2715ac2ef8",
      "expires_at": null,
      "cart": {
        "id": "0f50fb17-95c9-43e0-be6f-e3fb002672d7",
        "items": [
          {
            "id": "9119cd06-e239-4d76-9bb0-9c89504cc114",
            "quantity": 1,
            "product": {
              "id": "5df75457-ba03-4dc6-97c1-42d977e28da1",
              "name": "Cookies",
              "brand": {
                "id": "51244d3b-afef-44a6-a786-a5641621663d",
                "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": "15557150805@test.ongoody.com"
      },
      "workspace_id": "be6ba72a-7092-421a-8656-4b319b3816d5",
      "workspace_name": "Test Team",
      "original_cart": null,
      "original_amounts": null,
      "reference_id": "G94HSBOXV9PORJYFFZZ7NE0S",
      "payment_link": null
    }
  ],
  "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": "0f50fb17-95c9-43e0-be6f-e3fb002672d7",
    "items": [
      {
        "id": "9119cd06-e239-4d76-9bb0-9c89504cc114",
        "quantity": 1,
        "product": {
          "id": "5df75457-ba03-4dc6-97c1-42d977e28da1",
          "name": "Cookies",
          "brand": {
            "id": "51244d3b-afef-44a6-a786-a5641621663d",
            "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": "9f437d68-41a0-427d-ab87-e9330f4e045a",
  "sender": {
    "first_name": "Test",
    "last_name": "User",
    "email": "15557150805@test.ongoody.com"
  },
  "workspace_id": "be6ba72a-7092-421a-8656-4b319b3816d5",
  "workspace_name": "Test Team",
  "reference_id": "0QZRUC1PZAKOLYH3ULOZCHGN"
}

For a guide on how to create an order batch, see the Getting Started guide for the Automation API Getting Started guide or the Commerce API Getting Started 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 endpoint, or by receiving a webhook notification on the 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.

Authorizations

Authorization

string

headerrequired

Your Goody API key.

Body

application/json

from_name

string

required

The name of the sender of the order (typically a gift), to be displayed as "from".

message

string

For gifts, a message for the gift to be displayed in the digital unwrapping and email notifications, if enabled.

recipients

object[]

required

cart

object

required

send_method

enum<string>

required

The method for sending a order batch. email_and_link sends a gift email to the recipient (specify email for each recipient). link_multiple_custom_list generates a gift link without an automatic email. direct_send ships the product directly to the recipient (specify mailing_address for each recipient). For more information, see Send Methods.

Available options:

email_and_link,

link_multiple_custom_list,

direct_send

card_id

string

The digital greeting card to attach to gifts. A card must be specified if a message is specified, since the message is displayed after the card is opened.

payment_method_id

string

The payment method used to pay for this order batch. If not specified, defaults to the first payment method on the account. If the account has no payment methods, then the order batch creation will fail.

workspace_id

string

Workspace to create the order batch in. If not specified, creates the order batch in the oldest workspace the user has access to.

scheduled_send_on

string | null

The date and time at which the order batch will be sent. If not specified, the order batch is sent immediately. If an order batch is scheduled to be sent in the future, then orders will not be created until the scheduled send time. ISO 8601 format.

expires_at

string | null

The date and time at which the order batch will expire. If not specified, the order batch does not expire. An expiry must be set for orders paid using account balance. ISO 8601 format.

swap

enum<string>

What method to use to allow recipients to swap their gift. single (default) allows the recipient to swap the gift for one item, with hidden gift prices. multiple allows them to swap for multiple items up to the gift cost, with gift prices shown. disabled disables swapping on the gift. For gift collections (gift of choice), this must not be disabled.

Available options:

single,

multiple,

disabled

reserved_options

object | null

For approved API partners only.

Response

201 - application/json

string

required

send_status

enum<string>

required

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.

Available options:

pending,

complete,

failed,

canceled

from_name

string

required

The name of the sender. This is displayed on the order and notifications.

message

string | null

The message in this order batch, provided by the sender.

orders_count

integer

required

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.

orders_preview

object[]

required

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.

orders_preview.id

string

required

orders_preview.recipient_first_name

string

required

orders_preview.recipient_last_name

string | null

orders_preview.recipient_email

string | null

orders_preview.status

enum<string>

required

Available options:

created,

notified,

opened,

accepted,

pending_payment,

paid,

ordered,

shipped,

delivered,

failed,

canceled

orders_preview.individual_gift_link

string

required

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.

orders_preview.cart

object

required

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).

orders_preview.shipments

object[]

required

A list of the shipments for the order.

orders_preview.workspace_id

string | null

Organizations are sub-divided into workspaces. Orders are contained in workspaces, identified by this ID.

orders_preview.workspace_name

string | null

orders_preview.expires_at

string | null

For gifts, the date and time the gift is set to expire.

orders_preview.card_id

string | null

The digital greeting card on this gift.

orders_preview.message

string | null

The message in this gift, provided by the sender.

orders_preview.thank_you_note

string | null

A thank you note sent by the recipient.

orders_preview.view_count_recipient

integer

The number of times the recipient viewed the gift.

orders_preview.is_swapped

boolean

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.

orders_preview.order_batch_id

string

On Goody for Business, all orders are attached to a order batch, which is a collection of one or more orders.

orders_preview.amounts

object

required

Costs in USD cents (i.e. $1.00 = 100). If the order was swapped, amounts displays the most recent amounts (i.e. post-swap).

orders_preview.event_times

object | null

Only provided when calling the /orders/:id endpoint.

orders_preview.original_cart

object | null

If this order is a gift that was swapped, this displays the original cart that was sent to the recipient.

orders_preview.original_amounts

object | null

If this order is a gift that was swapped, this displays the original amounts of the cart that was sent to the recipient.

orders_preview.sender

object

required

The Goody user who sent this order.

orders_preview.payment_link

string | null

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).

orders_preview.reference_id

string

required

The reference ID displayed on receipts and other locations as the ID for this order.

recipients_count

integer

required

The total number of recipients in this order batch.

recipients_preview

object[]

required

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.

cart

object

required

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.

is_scheduled_send

boolean

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.

scheduled_send_on

string | null

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.

expires_at

string | null

The date and time the order batch is set to expire. ISO 8601, UTC.

send_method

enum<string> | null

Available options:

email_and_link,

link_multiple_custom_list,

direct_send

batch_name

string | null

An internal name for the order batch, falling back to an auto-generated batch name. Not displayed to recipients.

card_id

string | null

The digital greeting card on this order batch.

sender

object

required

The sender of the order batch.

workspace_id

string | null

Organizations are sub-divided into workspaces. Order batches are contained in workspaces, identified by this ID.

workspace_name

string | null

reference_id

string

required

The reference ID displayed on receipts and other locations as the ID for this order batch.

List all order batches

curl --request POST \
  --url https://api.ongoody.com/v1/order_batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "from_name": "John",
  "message": "Thank you!",
  "send_method": "link_multiple_custom_list",
  "payment_method_id": null,
  "workspace_id": null,
  "card_id": "9f437d68-41a0-427d-ab87-e9330f4e045a",
  "recipients": [
    {
      "first_name": "Alena",
      "last_name": "Kenter",
      "email": "alena@ongoody.com"
    },
    {
      "first_name": "Michael",
      "last_name": "Franci",
      "email": "michael@ongoody.com"
    }
  ],
  "cart": {
    "items": [
      {
        "product_id": "5df75457-ba03-4dc6-97c1-42d977e28da1",
        "quantity": 1
      }
    ]
  }
}'

{
  "id": "67dc1ba7-e1d2-4670-9feb-ae2715ac2ef8",
  "send_status": "complete",
  "from_name": "John",
  "message": "Thank you!",
  "orders_count": 2,
  "orders_preview": [
    {
      "id": "f1ff395d-c255-4eeb-bd3c-92e74a5fa240",
      "status": "created",
      "individual_gift_link": "https://gifts.ongoody.com/gift/7XXHPrJtLTaH4ti8WVQWB0Vx",
      "recipient_first_name": "Alena",
      "recipient_last_name": "Kenter",
      "recipient_email": "alena@ongoody.com",
      "card_id": "9f437d68-41a0-427d-ab87-e9330f4e045a",
      "message": "Thank you!",
      "thank_you_note": null,
      "view_count_recipient": 0,
      "is_swapped": false,
      "order_batch_id": "67dc1ba7-e1d2-4670-9feb-ae2715ac2ef8",
      "expires_at": null,
      "cart": {
        "id": "0f50fb17-95c9-43e0-be6f-e3fb002672d7",
        "items": [
          {
            "id": "9119cd06-e239-4d76-9bb0-9c89504cc114",
            "quantity": 1,
            "product": {
              "id": "5df75457-ba03-4dc6-97c1-42d977e28da1",
              "name": "Cookies",
              "brand": {
                "id": "51244d3b-afef-44a6-a786-a5641621663d",
                "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": "15557150805@test.ongoody.com"
      },
      "workspace_id": "be6ba72a-7092-421a-8656-4b319b3816d5",
      "workspace_name": "Test Team",
      "original_cart": null,
      "original_amounts": null,
      "reference_id": "A7SWKYWQDLWLOWU6G8NAHR6V",
      "payment_link": null
    },
    {
      "id": "a3e85fc1-6dca-45b6-bf27-48168f888504",
      "status": "created",
      "individual_gift_link": "https://gifts.ongoody.com/gift/rwCoTg9lb7TEmLvSIe7yCdX3",
      "recipient_first_name": "Michael",
      "recipient_last_name": "Franci",
      "recipient_email": "michael@ongoody.com",
      "card_id": "9f437d68-41a0-427d-ab87-e9330f4e045a",
      "message": "Thank you!",
      "thank_you_note": null,
      "view_count_recipient": 0,
      "is_swapped": false,
      "order_batch_id": "67dc1ba7-e1d2-4670-9feb-ae2715ac2ef8",
      "expires_at": null,
      "cart": {
        "id": "0f50fb17-95c9-43e0-be6f-e3fb002672d7",
        "items": [
          {
            "id": "9119cd06-e239-4d76-9bb0-9c89504cc114",
            "quantity": 1,
            "product": {
              "id": "5df75457-ba03-4dc6-97c1-42d977e28da1",
              "name": "Cookies",
              "brand": {
                "id": "51244d3b-afef-44a6-a786-a5641621663d",
                "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": "15557150805@test.ongoody.com"
      },
      "workspace_id": "be6ba72a-7092-421a-8656-4b319b3816d5",
      "workspace_name": "Test Team",
      "original_cart": null,
      "original_amounts": null,
      "reference_id": "G94HSBOXV9PORJYFFZZ7NE0S",
      "payment_link": null
    }
  ],
  "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": "0f50fb17-95c9-43e0-be6f-e3fb002672d7",
    "items": [
      {
        "id": "9119cd06-e239-4d76-9bb0-9c89504cc114",
        "quantity": 1,
        "product": {
          "id": "5df75457-ba03-4dc6-97c1-42d977e28da1",
          "name": "Cookies",
          "brand": {
            "id": "51244d3b-afef-44a6-a786-a5641621663d",
            "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": "9f437d68-41a0-427d-ab87-e9330f4e045a",
  "sender": {
    "first_name": "Test",
    "last_name": "User",
    "email": "15557150805@test.ongoody.com"
  },
  "workspace_id": "be6ba72a-7092-421a-8656-4b319b3816d5",
  "workspace_name": "Test Team",
  "reference_id": "0QZRUC1PZAKOLYH3ULOZCHGN"
}

Order Batches

Orders

Products

Payment Methods

Workspaces

Me

Schemas

Create an order batch

Order batches with 10 or fewer recipients

Order batches with more than 10 recipients

Authorizations

Body

Response

Order Batches

Orders

Products

Payment Methods

Workspaces

Me

Schemas

​Order batches with 10 or fewer recipients

​Order batches with more than 10 recipients

Authorizations

Body

Response

Order batches with 10 or fewer recipients

Order batches with more than 10 recipients