Create an order batch
Order batches with 10 or fewer recipients
Order batches with 10 or fewer recipients are created synchronously, and the returnedstatus 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 astatus 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.Body
Input parameters for an order batch.
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 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 A unique, client-supplied identifier for this order batch, which can be used as an idempotency key to prevent duplicate creation. If an order batch with the same customer_reference_id already exists for your account, the request is rejected with an error instead of creating a duplicate. Returned on the order batch as customer_reference_id.
Response
Order batch created using product URL in cart
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.
pending, complete, failed, canceled 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.
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 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