> ## Documentation Index
> Fetch the complete documentation index at: https://developer.ongoody.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/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.


## OpenAPI

````yaml POST /v1/order_batches
openapi: 3.0.1
info:
  title: Goody API
  version: 1.0.0
  contact:
    name: Goody Support
    email: support@ongoody.com
servers:
  - url: https://api.ongoody.com
    description: Production
  - url: https://api.sandbox.ongoody.com
    description: Sandbox
security: []
paths:
  /v1/order_batches:
    post:
      tags:
        - Order Batches
      summary: Create an order batch
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderBatchInput'
            examples:
              Order batch created:
                summary: Order batch created
                value:
                  from_name: John
                  message: Thank you!
                  send_method: link_multiple_custom_list
                  payment_method_id: null
                  workspace_id: null
                  card_id: fbbe04d8-2568-4f95-ab68-4589b757c521
                  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: 48680ddb-37b2-48b3-8380-226c07bdede2
                        quantity: 1
              Scheduled order batch created:
                summary: Scheduled order batch created
                value:
                  from_name: John
                  message: Thank you!
                  send_method: link_multiple_custom_list
                  payment_method_id: null
                  workspace_id: null
                  card_id: b5542d5f-e5d9-4f03-87a1-1a81dced6d45
                  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: 9ad51552-4b47-4a6f-9d9d-6c1d584d6511
                        quantity: 1
                  scheduled_send_on: '2026-06-10T12:24:24Z'
                  expires_at: '2026-07-01T12:24:24Z'
              Order batch created with recipient address:
                summary: Order batch created with recipient address
                value:
                  from_name: John
                  message: Thank you!
                  send_method: link_multiple_custom_list
                  payment_method_id: null
                  workspace_id: null
                  card_id: 5b0432b6-489f-4d66-b263-e8fb1f8bff2a
                  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
                    - first_name: Michael
                      last_name: Franci
                      email: michael@ongoody.com
                      mailing_address:
                        first_name: Michael
                        last_name: Franci
                        address_1: 1 Main St
                        address_2: Apt 124
                        city: New York
                        state: NY
                        postal_code: '10022'
                        country: US
                  cart:
                    items:
                      - product_id: 00a822ab-4d20-4e0c-bbd7-a572fdf9fef8
                        quantity: 1
              Order batch created using product URL in cart:
                summary: Order batch created using product URL in cart
                value:
                  from_name: John
                  message: Thank you!
                  send_method: link_multiple_custom_list
                  payment_method_id: null
                  workspace_id: null
                  card_id: fc8e36c5-e4c7-4ba4-93a1-bac37514230e
                  recipients:
                    - first_name: Alena
                      last_name: Kenter
                      email: alena@ongoody.com
                    - first_name: Michael
                      last_name: Franci
                      email: michael@ongoody.com
                  cart:
                    items:
                      - product_url: >-
                          http://example.com/browse/brands/cookie-company-1/cookies
                        quantity: 1
                  expires_at: '2026-07-01T12:24:40Z'
              Bad request:
                summary: Bad request
                value:
                  from_name: John
                  message: Thank you!
                  send_method: link_multiple_custom_list
                  payment_method_id: null
                  workspace_id: null
                  card_id: 1796e72f-0114-4436-993e-4ad3828f76a0
                  recipients: []
                  cart:
                    items:
                      - product_id: 51d3e838-8f30-4d56-985e-3e093705548d
                        quantity: 1
              Bad request when using invalid product URL in cart:
                summary: Bad request when using invalid product URL in cart
                value:
                  from_name: John
                  message: Thank you!
                  send_method: link_multiple_custom_list
                  payment_method_id: null
                  workspace_id: null
                  card_id: 203210fd-894b-4e9c-9fc5-7eb729c87d3b
                  recipients:
                    - first_name: Alena
                      last_name: Kenter
                      email: alena@ongoody.com
                    - first_name: Michael
                      last_name: Franci
                      email: michael@ongoody.com
                  cart:
                    items:
                      - product_url: >-
                          https://www.ongoody.com/browse/brands/invalid-brand/invalid-product
                        quantity: 1
                  scheduled_send_on: '2026-06-10T12:24:46Z'
                  expires_at: '2026-07-01T12:24:46Z'
      responses:
        '201':
          description: Order batch created using product URL in cart
          content:
            application/json:
              examples:
                Order batch created (10 or fewer recipients):
                  value:
                    id: 2fe7a598-bff4-4a4a-a423-47d9a6464a40
                    send_status: complete
                    from_name: John
                    message: Thank you!
                    orders_count: 2
                    orders_preview:
                      - id: a3316403-9b84-4b55-92d6-453dcc3e5b48
                        status: created
                        individual_gift_link: >-
                          https://gifts.ongoody.com/gift/3KwUVkzoygOD0OyNQba9bg4h
                        recipient_first_name: Alena
                        recipient_last_name: Kenter
                        recipient_email: alena@ongoody.com
                        card_id: fbbe04d8-2568-4f95-ab68-4589b757c521
                        message: Thank you!
                        thank_you_note: null
                        view_count_recipient: 0
                        is_swapped: false
                        order_batch_id: 2fe7a598-bff4-4a4a-a423-47d9a6464a40
                        expires_at: null
                        cart:
                          id: 4d42623b-4842-4f16-b58d-d346181bf688
                          items:
                            - id: 9c8547f2-7331-4084-9b29-042c4b5e74e4
                              quantity: 1
                              product:
                                id: 48680ddb-37b2-48b3-8380-226c07bdede2
                                name: Cookies
                                brand:
                                  id: 002daabe-9cd2-486f-9729-11b7df740105
                                  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: 15558842084@test.ongoody.com
                        workspace_id: a1002766-acb7-432c-ada3-d832309d1353
                        workspace_name: Test Team
                        original_cart: null
                        original_amounts: null
                        reference_id: JEUYIPRNHZX6C1K4RZMSCV7G
                        payment_link: null
                      - id: 0033096f-637b-408d-821b-59c60aadfc01
                        status: created
                        individual_gift_link: >-
                          https://gifts.ongoody.com/gift/DP31GxMZ5rOWRwollNdi8HCN
                        recipient_first_name: Michael
                        recipient_last_name: Franci
                        recipient_email: michael@ongoody.com
                        card_id: fbbe04d8-2568-4f95-ab68-4589b757c521
                        message: Thank you!
                        thank_you_note: null
                        view_count_recipient: 0
                        is_swapped: false
                        order_batch_id: 2fe7a598-bff4-4a4a-a423-47d9a6464a40
                        expires_at: null
                        cart:
                          id: 4d42623b-4842-4f16-b58d-d346181bf688
                          items:
                            - id: 9c8547f2-7331-4084-9b29-042c4b5e74e4
                              quantity: 1
                              product:
                                id: 48680ddb-37b2-48b3-8380-226c07bdede2
                                name: Cookies
                                brand:
                                  id: 002daabe-9cd2-486f-9729-11b7df740105
                                  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: 15558842084@test.ongoody.com
                        workspace_id: a1002766-acb7-432c-ada3-d832309d1353
                        workspace_name: Test Team
                        original_cart: null
                        original_amounts: null
                        reference_id: OSPHLVULRNQDZQYT080V1ZOF
                        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: 4d42623b-4842-4f16-b58d-d346181bf688
                      items:
                        - id: 9c8547f2-7331-4084-9b29-042c4b5e74e4
                          quantity: 1
                          product:
                            id: 48680ddb-37b2-48b3-8380-226c07bdede2
                            name: Cookies
                            brand:
                              id: 002daabe-9cd2-486f-9729-11b7df740105
                              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: fbbe04d8-2568-4f95-ab68-4589b757c521
                    sender:
                      first_name: Test
                      last_name: User
                      email: 15558842084@test.ongoody.com
                    workspace_id: a1002766-acb7-432c-ada3-d832309d1353
                    workspace_name: Test Team
                    reference_id: NJNJ27PDL9JAKIEBYPFUFAHG
                    customer_reference_id: null
                Order batch created (more than 10 recipients):
                  value:
                    id: 703dbcda-f9f3-481f-b884-ee7f24b5fcb4
                    send_status: pending
                    from_name: John
                    message: Thank you!
                    orders_count: 0
                    orders_preview: []
                    recipients_count: 11
                    recipients_preview:
                      - first_name: Alena
                        last_name: Kenter
                        email: alena@ongoody.com
                      - first_name: Michael
                        last_name: Franci
                        email: michael@ongoody.com
                      - first_name: Alena
                        last_name: Kenter
                        email: alena@ongoody.com
                      - first_name: Michael
                        last_name: Franci
                        email: michael@ongoody.com
                      - first_name: Alena
                        last_name: Kenter
                        email: alena@ongoody.com
                      - first_name: Michael
                        last_name: Franci
                        email: michael@ongoody.com
                      - first_name: Alena
                        last_name: Kenter
                        email: alena@ongoody.com
                      - first_name: Michael
                        last_name: Franci
                        email: michael@ongoody.com
                      - first_name: Alena
                        last_name: Kenter
                        email: alena@ongoody.com
                      - first_name: Michael
                        last_name: Franci
                        email: michael@ongoody.com
                    cart:
                      id: 5e2514a9-2ff0-4149-a24e-15de787ed79e
                      items:
                        - id: d5a43998-58fd-4a0b-9e58-5615beb81e01
                          quantity: 1
                          product:
                            id: 3c638d59-f520-4e1d-aed8-25b2506dcb59
                            name: Cookies
                            brand:
                              id: 202ac25d-fa1a-410d-a795-0cd2cb430ec1
                              name: Cookie Company
                    is_scheduled_send: false
                    scheduled_send_on: null
                    expires_at: null
                    send_method: link_multiple_custom_list
                    batch_name: 0 recipients
                    card_id: 3da5c301-a121-4fa2-9058-16cc09f10368
                    sender:
                      first_name: Test
                      last_name: User
                      email: 15558842084@test.ongoody.com
                    workspace_id: a1002766-acb7-432c-ada3-d832309d1353
                    workspace_name: Test Team
                    reference_id: XMEEL7QJU7WHTFX4QHNJAAEF
                    customer_reference_id: null
                Scheduled order batch created:
                  value:
                    id: 7e96ff95-9ad6-4712-8c88-bd9b44158ef0
                    send_status: pending
                    from_name: John
                    message: Thank you!
                    orders_count: 0
                    orders_preview: []
                    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: d8574b3d-4f5a-498d-aaf6-91ee0b052a7c
                      items:
                        - id: cd403ad9-432b-40a1-b259-e489f9212e56
                          quantity: 1
                          product:
                            id: 9ad51552-4b47-4a6f-9d9d-6c1d584d6511
                            name: Cookies
                            brand:
                              id: 8a80c8bb-7544-4eeb-a162-e63546ad8312
                              name: Cookie Company
                    is_scheduled_send: true
                    scheduled_send_on: '2026-06-10T12:24:24Z'
                    expires_at: '2026-07-01T12:24:24Z'
                    send_method: link_multiple_custom_list
                    batch_name: Alena Kenter and Michael Franci
                    card_id: b5542d5f-e5d9-4f03-87a1-1a81dced6d45
                    sender:
                      first_name: Test
                      last_name: User
                      email: 15558842084@test.ongoody.com
                    workspace_id: a1002766-acb7-432c-ada3-d832309d1353
                    workspace_name: Test Team
                    reference_id: XQPQQLYJ2GJNSZMYRHPQGO0H
                    customer_reference_id: null
                Order batch created with recipient address:
                  value:
                    id: c80f3909-3f23-4075-bf90-6951a5ed8b27
                    send_status: complete
                    from_name: John
                    message: Thank you!
                    orders_count: 2
                    orders_preview:
                      - id: 16b29623-4d60-41b0-94ee-b81f9bb1d9aa
                        status: created
                        individual_gift_link: >-
                          https://gifts.ongoody.com/gift/APTvshiuXF2zAo2rI0ktJKow
                        recipient_first_name: Alena
                        recipient_last_name: Kenter
                        recipient_email: alena@ongoody.com
                        card_id: 5b0432b6-489f-4d66-b263-e8fb1f8bff2a
                        message: Thank you!
                        thank_you_note: null
                        view_count_recipient: 0
                        is_swapped: false
                        order_batch_id: c80f3909-3f23-4075-bf90-6951a5ed8b27
                        expires_at: null
                        cart:
                          id: d1afca1b-5f78-4d42-a4bf-1928836f9bd4
                          items:
                            - id: cfc83321-24d0-440f-9083-4cc15e8849bf
                              quantity: 1
                              product:
                                id: 00a822ab-4d20-4e0c-bbd7-a572fdf9fef8
                                name: Cookies
                                brand:
                                  id: 8552d59e-f14f-4120-a8e1-8a6f4e49b89d
                                  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: 15558842084@test.ongoody.com
                        workspace_id: a1002766-acb7-432c-ada3-d832309d1353
                        workspace_name: Test Team
                        original_cart: null
                        original_amounts: null
                        reference_id: O2USE6TOSFUMEGQLFWY7KZ4K
                        payment_link: null
                      - id: 206b70c1-21c1-4061-8a4f-5381ad7a7d1e
                        status: created
                        individual_gift_link: >-
                          https://gifts.ongoody.com/gift/v6UyaGtEnNHa6oKGkPz2WZ0j
                        recipient_first_name: Michael
                        recipient_last_name: Franci
                        recipient_email: michael@ongoody.com
                        card_id: 5b0432b6-489f-4d66-b263-e8fb1f8bff2a
                        message: Thank you!
                        thank_you_note: null
                        view_count_recipient: 0
                        is_swapped: false
                        order_batch_id: c80f3909-3f23-4075-bf90-6951a5ed8b27
                        expires_at: null
                        cart:
                          id: d1afca1b-5f78-4d42-a4bf-1928836f9bd4
                          items:
                            - id: cfc83321-24d0-440f-9083-4cc15e8849bf
                              quantity: 1
                              product:
                                id: 00a822ab-4d20-4e0c-bbd7-a572fdf9fef8
                                name: Cookies
                                brand:
                                  id: 8552d59e-f14f-4120-a8e1-8a6f4e49b89d
                                  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: 15558842084@test.ongoody.com
                        workspace_id: a1002766-acb7-432c-ada3-d832309d1353
                        workspace_name: Test Team
                        original_cart: null
                        original_amounts: null
                        reference_id: G8LJ2WRXAIW4NHQFMQOWYAGI
                        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: d1afca1b-5f78-4d42-a4bf-1928836f9bd4
                      items:
                        - id: cfc83321-24d0-440f-9083-4cc15e8849bf
                          quantity: 1
                          product:
                            id: 00a822ab-4d20-4e0c-bbd7-a572fdf9fef8
                            name: Cookies
                            brand:
                              id: 8552d59e-f14f-4120-a8e1-8a6f4e49b89d
                              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: 5b0432b6-489f-4d66-b263-e8fb1f8bff2a
                    sender:
                      first_name: Test
                      last_name: User
                      email: 15558842084@test.ongoody.com
                    workspace_id: a1002766-acb7-432c-ada3-d832309d1353
                    workspace_name: Test Team
                    reference_id: IOMT5YVUWZFFAX5CTGMHTUZ9
                    customer_reference_id: null
                Order batch created (using product URL in cart):
                  value:
                    id: ffa13115-d567-4081-8e93-12a72e49aa54
                    send_status: complete
                    from_name: John
                    message: Thank you!
                    orders_count: 2
                    orders_preview:
                      - id: 47d19ed3-1ce7-471d-bb72-e017007c9c8a
                        status: created
                        individual_gift_link: >-
                          https://gifts.ongoody.com/gift/RHsVV7JepMuHRljl6nWens5x
                        recipient_first_name: Alena
                        recipient_last_name: Kenter
                        recipient_email: alena@ongoody.com
                        card_id: fc8e36c5-e4c7-4ba4-93a1-bac37514230e
                        message: Thank you!
                        thank_you_note: null
                        view_count_recipient: 0
                        is_swapped: false
                        order_batch_id: ffa13115-d567-4081-8e93-12a72e49aa54
                        expires_at: '2026-07-01T12:24:40Z'
                        cart:
                          id: 5757add5-57ca-4a44-8fea-698368b651b7
                          items:
                            - id: 26c6d966-99a7-4e37-9874-917d9f4ef7ae
                              quantity: 1
                              product:
                                id: ad76b601-2074-4772-b5bf-4af442502183
                                name: Cookies
                                brand:
                                  id: 6538b48d-2537-46b4-9afc-5d3997fc50da
                                  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: 15558842084@test.ongoody.com
                        workspace_id: a1002766-acb7-432c-ada3-d832309d1353
                        workspace_name: Test Team
                        original_cart: null
                        original_amounts: null
                        reference_id: 3SFN2R3FR8O3WAOXXLENCQJH
                        payment_link: null
                      - id: 7e3f9c70-6366-45ba-a229-a748928d0768
                        status: created
                        individual_gift_link: >-
                          https://gifts.ongoody.com/gift/STQ08GcZCWSxTH9Q2yN6Mll6
                        recipient_first_name: Michael
                        recipient_last_name: Franci
                        recipient_email: michael@ongoody.com
                        card_id: fc8e36c5-e4c7-4ba4-93a1-bac37514230e
                        message: Thank you!
                        thank_you_note: null
                        view_count_recipient: 0
                        is_swapped: false
                        order_batch_id: ffa13115-d567-4081-8e93-12a72e49aa54
                        expires_at: '2026-07-01T12:24:40Z'
                        cart:
                          id: 5757add5-57ca-4a44-8fea-698368b651b7
                          items:
                            - id: 26c6d966-99a7-4e37-9874-917d9f4ef7ae
                              quantity: 1
                              product:
                                id: ad76b601-2074-4772-b5bf-4af442502183
                                name: Cookies
                                brand:
                                  id: 6538b48d-2537-46b4-9afc-5d3997fc50da
                                  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: 15558842084@test.ongoody.com
                        workspace_id: a1002766-acb7-432c-ada3-d832309d1353
                        workspace_name: Test Team
                        original_cart: null
                        original_amounts: null
                        reference_id: NQDOPHIAMN2R3KQOQT3USQDH
                        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: 5757add5-57ca-4a44-8fea-698368b651b7
                      items:
                        - id: 26c6d966-99a7-4e37-9874-917d9f4ef7ae
                          quantity: 1
                          product:
                            id: ad76b601-2074-4772-b5bf-4af442502183
                            name: Cookies
                            brand:
                              id: 6538b48d-2537-46b4-9afc-5d3997fc50da
                              name: Cookie Company
                    is_scheduled_send: false
                    scheduled_send_on: null
                    expires_at: '2026-07-01T12:24:40Z'
                    send_method: link_multiple_custom_list
                    batch_name: Alena Kenter and Michael Franci
                    card_id: fc8e36c5-e4c7-4ba4-93a1-bac37514230e
                    sender:
                      first_name: Test
                      last_name: User
                      email: 15558842084@test.ongoody.com
                    workspace_id: a1002766-acb7-432c-ada3-d832309d1353
                    workspace_name: Test Team
                    reference_id: 8K4BAROWNJADABI25LWWG3W1
                    customer_reference_id: null
              schema:
                $ref: '#/components/schemas/OrderBatch'
        '400':
          description: Bad request when using invalid product URL in cart
          content:
            application/json:
              examples:
                Order batch without recipients fails to create:
                  value:
                    error: Recipients can't be blank
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearer: []
components:
  schemas:
    OrderBatchInput:
      type: object
      description: Input parameters for an order batch.
      properties:
        from_name:
          type: string
          description: >-
            The name of the sender of the order (typically a gift), to be
            displayed as "from".
        message:
          type: string
          description: >-
            For gifts, a message for the gift to be displayed in the digital
            unwrapping and email notifications, if enabled.
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/RecipientInput'
        cart:
          $ref: '#/components/schemas/CartInput'
        send_method:
          $ref: '#/components/schemas/OrderBatchSendMethod'
        card_id:
          type: string
          format: uuid
          description: >-
            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:
          type: string
          description: >-
            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:
          type: string
          format: uuid
          description: >-
            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:
          type: string
          format: date-time
          description: >-
            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.
          nullable: true
        expires_at:
          type: string
          format: date-time
          description: >-
            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.
          nullable: true
        swap:
          $ref: '#/components/schemas/OrderBatchSwap'
        international_shipping_tier:
          $ref: '#/components/schemas/OrderBatchInternationalShippingTier'
        international_gift_cards_enabled:
          type: boolean
          description: >-
            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.
        notifications_enabled:
          type: boolean
          description: >-
            Direct Send only. Whether to enable notifications for Direct Send
            orders. If `true`, we send confirmation and shipping notifications
            to Direct Send recipients. If `false`, we do not send any
            notifications to Direct Send recipients.
        commerce_end_user_id:
          type: string
          nullable: true
          description: >-
            If associating this gift with a Commerce End User (i.e. your app's
            user), provide the user ID here. Required if using a Commerce User
            Payment Method in the `payment_method_id` field.
        customer_reference_id:
          type: string
          nullable: true
          description: >-
            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`.
        reserved_options:
          type: object
          description: For approved API partners only.
          properties:
            custom_price_tier:
              type: integer
              nullable: true
              description: >-
                For approved API partners only. A custom price tier to set on
                this order batch.
          nullable: true
      required:
        - from_name
        - recipients
        - cart
        - send_method
    OrderBatch:
      type: object
      description: >-
        An order batch is the primary resource created by the API. Order batches
        contain an array of orders.
      properties:
        id:
          type: string
          format: uuid
        send_status:
          $ref: '#/components/schemas/OrderBatchSendStatus'
          description: >-
            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.
        from_name:
          type: string
          description: >-
            The name of the sender. This is displayed on the order and
            notifications.
        message:
          type: string
          nullable: true
          description: The message in this order batch, provided by the sender.
        orders_count:
          type: integer
          description: >-
            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:
          type: array
          items:
            $ref: '#/components/schemas/Order'
          description: >-
            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.
        recipients_count:
          type: integer
          description: The total number of recipients in this order batch.
        recipients_preview:
          type: array
          items:
            $ref: '#/components/schemas/OrderBatchRecipient'
          description: >-
            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:
          $ref: '#/components/schemas/Cart'
          description: >-
            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:
          type: boolean
          description: >-
            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:
          type: string
          format: date-time
          description: >-
            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.
          nullable: true
        expires_at:
          type: string
          format: date-time
          description: The date and time the order batch is set to expire. ISO 8601, UTC.
          nullable: true
        send_method:
          $ref: '#/components/schemas/OrderBatchSendMethod'
          nullable: true
        batch_name:
          type: string
          nullable: true
          description: >-
            An internal name for the order batch, falling back to an
            auto-generated batch name. Not displayed to recipients.
        card_id:
          type: string
          format: uuid
          nullable: true
          description: The digital greeting card on this order batch.
        sender:
          $ref: '#/components/schemas/Sender'
          description: The sender of the order batch.
        workspace_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            Organizations are sub-divided into workspaces. Order batches are
            contained in workspaces, identified by this ID.
        workspace_name:
          type: string
          nullable: true
        reference_id:
          type: string
          description: >-
            The reference ID displayed on receipts and other locations as the ID
            for this order batch.
        customer_reference_id:
          type: string
          nullable: true
          description: >-
            A unique client-supplied reference for this order batch, provided on
            creation to prevent duplicate order batches. Returns the value sent
            when the batch was created, or `null` if none was provided.
      required:
        - id
        - send_status
        - orders_preview
        - orders_count
        - cart
        - from_name
        - recipients_preview
        - recipients_count
        - sender
        - reference_id
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
    RecipientInput:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
        phone:
          type: string
          nullable: true
          description: >-
            Optional. Phone number for text notifications. E164 format (e.g.
            +15552347890), US only.
        mailing_address:
          $ref: '#/components/schemas/MailingAddress'
          description: >-
            Optional mailing address to pre-populate into the order. This field
            is only available for approved API partners.
      required:
        - first_name
    CartInput:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CartItemInput'
          description: An array of cart items.
    OrderBatchSendMethod:
      type: string
      enum:
        - email_and_link
        - link_multiple_custom_list
        - direct_send
      description: >-
        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](/introduction/send-methods).
    OrderBatchSwap:
      type: string
      enum:
        - single
        - multiple
        - disabled
      description: >-
        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`.
    OrderBatchInternationalShippingTier:
      type: string
      enum:
        - disabled
        - standard
        - full
      description: >-
        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.
    OrderBatchSendStatus:
      type: string
      enum:
        - pending
        - complete
        - failed
        - canceled
    Order:
      type: object
      description: >-
        An individual order contains the gift link to be sent to the recipient
        (if applicable) and other information about the order.
      properties:
        id:
          type: string
          format: uuid
        recipient_first_name:
          type: string
        recipient_last_name:
          type: string
          nullable: true
        recipient_email:
          type: string
          nullable: true
        status:
          $ref: '#/components/schemas/OrderStatus'
        individual_gift_link:
          type: string
          description: >-
            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.
        cart:
          $ref: '#/components/schemas/Cart'
          description: >-
            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).
        cart_selections:
          type: array
          items:
            $ref: '#/components/schemas/CartSelection'
          description: >-
            Product variant selections for each cart product. Only for commerce
            app orders.
          nullable: true
        shipments:
          type: array
          items:
            $ref: '#/components/schemas/Shipment'
          description: A list of the shipments for the order.
        workspace_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            Organizations are sub-divided into workspaces. Orders are contained
            in workspaces, identified by this ID.
        workspace_name:
          type: string
          nullable: true
        expires_at:
          type: string
          format: date-time
          description: For gifts, the date and time the gift is set to expire.
          nullable: true
        card_id:
          type: string
          format: uuid
          nullable: true
          description: The digital greeting card on this gift.
        message:
          type: string
          nullable: true
          description: The message in this gift, provided by the sender.
        thank_you_note:
          type: string
          nullable: true
          description: A thank you note sent by the recipient.
        view_count_recipient:
          type: integer
          description: The number of times the recipient viewed the gift.
        is_swapped:
          type: boolean
          description: >-
            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`.
        order_batch_id:
          type: string
          format: uuid
          description: >-
            On Goody for Business, all orders are attached to a order batch,
            which is a collection of one or more orders.
        amounts:
          type: object
          description: >-
            Costs in USD cents (i.e. $1.00 = 100). If the order was swapped,
            `amounts` displays the most recent amounts (i.e. post-swap).
          properties:
            amount_product:
              type: integer
              description: Total cost of the products in this order.
            amount_shipping:
              type: integer
              description: Total cost of shipping for this order.
            amount_processing_fee:
              type: integer
              nullable: true
              description: Total cost of processing fees for this order.
            amount_credit_applied:
              type: integer
              nullable: true
              description: Total amount of credit applied to this order.
            amount_pre_tax_total:
              type: integer
              description: >-
                Total cost of the products, shipping, and processing fees in
                this order.
            amount_tax:
              type: integer
              nullable: true
              description: Total tax for this order.
            amount_total:
              type: integer
              nullable: true
              description: >-
                Total cost of the products, shipping, processing fees, tax, and
                global shipping costs in this order.
            amount_global_relay_cost:
              type: integer
              nullable: true
              description: >-
                Total cost of global shipping for this order through the Global
                Relay service.
          required:
            - amount_product
            - amount_shipping
            - amount_pre_tax_total
        event_times:
          type: object
          description: Only provided when calling the /orders/:id endpoint.
          properties:
            created_at:
              type: string
              format: date-time
              description: ISO 8601
            notified_at:
              type: string
              format: date-time
              description: When the recipient was notified of the order.
              nullable: true
            opened_at:
              type: string
              format: date-time
              description: For gifts, when the recipient opened the order.
              nullable: true
            accepted_at:
              type: string
              format: date-time
              description: For gifts, when the recipient accepted the order.
              nullable: true
            pending_payment_at:
              type: string
              format: date-time
              description: When the order entered pending payment status.
              nullable: true
            paid_at:
              type: string
              format: date-time
              description: When the order was paid for.
              nullable: true
            shipped_at:
              type: string
              format: date-time
              description: >-
                When the order was first shipped. If there are multiple
                shipments, this is when the first shipment shipped.
              nullable: true
            delivered_at:
              type: string
              format: date-time
              description: >-
                When the order was delivered. If there are multiple shipments,
                this is when all shipments were delivered.
              nullable: true
          required:
            - created_at
          nullable: true
        original_cart:
          $ref: '#/components/schemas/Cart'
          description: >-
            If this order is a gift that was swapped, this displays the original
            cart that was sent to the recipient.
          nullable: true
        original_amounts:
          type: object
          description: >-
            If this order is a gift that was swapped, this displays the original
            amounts of the cart that was sent to the recipient.
          properties:
            original_amount_product:
              type: integer
              nullable: true
            original_amount_shipping:
              type: integer
              nullable: true
            original_amount_credit_applied:
              type: integer
              nullable: true
            original_amount_pre_tax_total:
              type: integer
              nullable: true
          nullable: true
        sender:
          $ref: '#/components/schemas/Sender'
          description: The Goody user who sent this order.
        payment_link:
          type: string
          nullable: true
          description: >-
            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).
        reference_id:
          type: string
          description: >-
            The reference ID displayed on receipts and other locations as the ID
            for this order.
      required:
        - id
        - recipient_first_name
        - status
        - individual_gift_link
        - cart
        - shipments
        - amounts
        - sender
        - reference_id
    OrderBatchRecipient:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
      required:
        - first_name
    Cart:
      type: object
      properties:
        id:
          type: string
          format: uuid
        items:
          type: array
          items:
            $ref: '#/components/schemas/CartItem'
    Sender:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
      required:
        - first_name
        - last_name
        - email
    MailingAddress:
      type: object
      properties:
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        address_1:
          type: string
        address_2:
          type: string
          nullable: true
        city:
          type: string
        state:
          type: string
        postal_code:
          type: string
        country:
          type: string
          nullable: true
          description: >-
            The two-letter country code, e.g. "US". Only US is supported at this
            time.
      required:
        - address_1
        - city
        - state
        - postal_code
        - country
    CartItemInput:
      type: object
      properties:
        product_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            ID of the product. Preferred over URL since this is always stable.
            Either `product_id` or `product_url` must be provided.
        product_url:
          type: string
          nullable: true
          description: >-
            URL of the product. Either `product_id` or `product_url` must be
            provided.
        quantity:
          type: integer
        variable_price:
          type: integer
          description: >-
            If this product has a variable price (e.g. a flex gift or a gift
            card), then this must be provided. A positive integer represented in
            cents.
        variants:
          type: array
          items:
            type: string
          description: >-
            An array of variant names (not IDs). When using the Direct Send send
            method with a product with variants, the variants must be provided.
            The length of the array must be equal to `variants_num_selectable`
            on the product, and the variants must come from the names of the
            `varaints` on the product. For example, for a t-shirt with
            `variants_num_selectable` = 1 and variants S, M, L, pass ['M']. Or,
            for a box of cookies with `variants_num_selectable` = 2 and variants
            Sugar, Caramel, Chocolate, pass ['Sugar', 'Chocolate'].
      required:
        - product_id
        - quantity
    OrderStatus:
      type: string
      enum:
        - created
        - notified
        - opened
        - accepted
        - pending_payment
        - paid
        - ordered
        - shipped
        - delivered
        - failed
        - canceled
    CartSelection:
      type: object
      description: Product variant selections for a specific gift cart product.
      properties:
        id:
          type: string
          format: uuid
        cart_item_id:
          type: string
          format: uuid
          description: >-
            The cart item ID this selection belongs to. Match this with
            cart.items[].id.
        quantity_index:
          type: integer
          description: >-
            The index of this selection within multiple quantities of the same
            product. If a given cart product has multiple quantities, this will
            be 0 for the first unit, 1 for the second unit, etc.
        variants:
          type: array
          items:
            type: string
          description: The selected variants for this product selection and quantity index.
      required:
        - id
        - cart_item_id
        - quantity_index
        - variants
    Shipment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - pending
            - tracking
            - shipped
            - delivered
            - delivered_override
            - failed
            - failed_unset_tracking
            - failed_with_reship
        brand_name:
          type: string
          description: The name of the brand that this shipment is from.
        tracking_carrier:
          type: string
          nullable: true
          description: The carrier for this shipment, e.g. UPS.
        tracking_number:
          type: string
          nullable: true
          description: Only for approved distribution partners.
        tracking_url:
          type: string
          nullable: true
          description: Only for approved distribution partners.
        shipped_at:
          type: string
          format: date-time
          description: ISO 8601
          nullable: true
        delivered_at:
          type: string
          format: date-time
          description: ISO 8601
          nullable: true
        delivery_eta:
          type: string
          format: date-time
          description: The estimated delivery time of this shipment.
          nullable: true
      required:
        - id
        - status
        - brand_name
    CartItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
        product:
          type: object
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
            brand:
              type: object
              description: The brand that this product is from.
              properties:
                id:
                  type: string
                  format: uuid
                name:
                  type: string
              required:
                - id
                - name
          required:
            - id
            - name
            - brand
        quantity:
          type: integer
      required:
        - id
        - product
        - quantity
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: Your Goody API key.

````