Create an order batch
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
Your Goody API key.
Body
The name of the sender of the order (typically a gift), to be displayed as "from".
For gifts, a message for the gift to be displayed in the digital unwrapping and email notifications, if enabled.
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.
email_and_link
, link_multiple_custom_list
, direct_send
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.
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 to create the order batch in. If not specified, creates the order batch in the oldest workspace the user has access to.
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.
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.
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
.
single
, multiple
, disabled
Whether to enable international shipping on this order. disabled
(default) only enables US shipping on this order. standard
combined with international_gift_cards_enabled
enables international gift cards. full
enables the full global catalog for 100+ countries, with additional tax, duties, and freight costs.
disabled
, standard
, full
Whether to enable international gift cards on this order. If true
and the international_shipping_tier
is standard
, then international gift cards can be swapped to. If false
, then international gift cards are not available to be swapped to. Note that this setting does not currently apply if international_shipping_tier
is full
.
For approved API partners only.
Response
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.
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.
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. 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.
email_and_link
, link_multiple_custom_list
, direct_send
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.