goody_order_batches_create - Goody Developers

Permission: Send gifts · Workspace: required (from goody_workspaces_list) Sends a gift batch — charges the payment method and generates the gift links.

This spends real money and cannot be undone from here. Preview or price first, relay the total, and only call this after the user confirms both the price and the recipients.

Parameters

workspace_id

string

required

Workspace UUID — from goody_workspaces_list. Charges and sends from this workspace.

payment_method_id

string

required

The funding source — from goody_payment_methods_list. A saved-card UUID, or the literal BALANCE, WORKSPACE_BALANCE, or CORPORATE_ACCOUNT sentinel.

card_id

string

required

Card UUID — from goody_cards_list. The card the recipient sees with the gift.

confirmed

boolean

required

Must be the literal true — the tool rejects anything else. Pass true only after the user has approved the price and recipients.

send_method

string

required

How each recipient receives the gift. No default — you must choose one:

link_single — the recipient is not auto-notified; you share the link yourself.
email_and_link — Goody emails each recipient their gift link.
direct_send — Goody ships the physical product to each recipient’s mailing_address, with no email. The contact_id shorthand can’t be combined with direct_send.

product_id

string

A single product UUID — from goody_products_search. Use this or cart, never both.

quantity

integer

default:"1"

Quantity for product_id. Defaults to 1.

variable_price

integer

Amount to fund, in cents, for a variable-amount Gift of Choice or variable gift card. Must fall within the gift’s [price_min, price_max]. Only applies to product_id.

cart

object

A multi-item cart — an object with an items array (not a bare array). Use this or product_id, never both.

Show cart

items

object[]

required

One entry per product in the gift.

Show item

product_id

string

required

Product UUID.

quantity

integer

default:"1"

Quantity of this product.

variable_price

integer

Amount in cents for a variable-amount gift, within its [price_min, price_max].

variants

string[]

Selected variant option IDs (e.g. size, color) for products that offer them.

contact_id

string

A single saved-contact UUID — from goody_contacts_search. Use this or recipients. Cannot be combined with direct_send.

recipients

object[]

The people to send to. Use this or contact_id.

Show recipient

name

string

Full name — split on the first space (first token → first name, the rest → last name). Use this or first_name + last_name.

first_name

string

First name. Pair with last_name.

last_name

string

Last name.

string

Recipient email.

phone

string

Recipient phone, when sending by text.

contact_id

string

Link this recipient to an existing saved contact.

mailing_address

object

Required on every recipient when send_method is direct_send.

Show mailing_address

first_name

string

Recipient first name for the shipping label.

last_name

string

Recipient last name for the shipping label.

address_1

string

required

Street address.

address_2

string

Apartment, suite, etc.

city

string

required

City.

state

string

required

State or province.

postal_code

string

required

ZIP or postal code.

country

string

required

Country.

message

string

The note shown on the gift card. Use goody_messages_generate to draft one.

from_name

string

The “From” name the recipient sees. Defaults to the authenticated user.

swap

string

default:"single"

Whether the recipient may swap the gift. One of single (swap once), multiple (swap freely), or disabled (no swapping).

scheduled_send_on

string

ISO 8601 datetime to delay sending. Must be in the future and at most 3 months out — anchor “now” to goody_me_get’s server_time.

expires_at

string

ISO 8601 datetime the gift expires if the recipient hasn’t accepted it. Required when paying from BALANCE. The standard default is about 10 weeks. Mutually exclusive with expires_on.

expires_on

string

Date alias YYYY-MM-DD, coerced to end of day. Mutually exclusive with expires_at.

alcohol_age_verification_attested

boolean

Must be true when the cart contains alcohol.

international_shipping_tier

string

default:"disabled"

How far the gift can ship. One of disabled (default; US & Canada only), standard, or full (global, 140+ countries; up to about $55/order in taxes, tariffs, and freight).

international_gift_cards_enabled

boolean

Lets recipients outside supported regions swap their gift for a gift card.

custom_form_id

string

Attach an existing custom form’s recipient questions to the gift.

Alcohol gifts require the account to be alcohol-enabled, cannot be paid from BALANCE, and require alcohol_age_verification_attested: true.

Returns

order_batch

object

The created batch.

Show order_batch

string

Batch UUID — pass as order_batch_id to goody_order_batches_get or goody_orders_list.

public_id

string

The batch’s public identifier.

status

string

Where the batch is in its lifecycle.

preview_url

string | null

A shareable URL that renders the sent gift. Lead your reply with this.

sender_preview_urls

string[]

Per-recipient sender-view links.

payment_method

object | null

The funding source that was charged.

Show payment_method

string

The payment-method UUID, or the BALANCE / WORKSPACE_BALANCE / CORPORATE_ACCOUNT sentinel.

name

string

Display name, e.g. “Visa 1234”.

notification_summary

string | null

Whether and how recipients were notified. State this to the user.

suggested_next_steps

string[]

Follow-on actions you can offer the user.

Example

"Yes, send it."

Build the confirmation step with goody_order_batches_preview before calling this. To make a one-off gift recurring, offer goody_autogift_rules_create.

​Parameters

​Returns

​Example

Parameters

Returns

Example