Skip to main content
POST
Place an order - v3
Use this endpoint to create a new order for a specific product variant on behalf of a recipient via the Direct Fulfillment integration. Use this when you already know the recipient’s shipping address and the exact variant to ship - V3 collapses gift creation and order placement into a single idempotent call.
Upcoming change (November 12, 2026):
  • Orders missing localizedFields.taxNumber for a destination that requires it will be rejected with 400 and errorCode 400_ORDS_008.
  • Orders with a postalCode that doesn’t match the destination country’s format (e.g. a US ZIP code containing letters) will be rejected with 400 and errorCode 400_ORDS_009.
  • To catch invalid postal codes before placing the order, validate user-entered addresses with POST /v3/orders/addresses/validate - it applies the same postal code check and returns the same error. See the Changelog for details.
Required fields:
  • billingMethodId - the Billing Method that will pay for the order. Must belong to the specified Account. Use GET /v3/billing-methods to discover available methods.
  • variantId - the specific product variant to order. Use GET /v3/products to browse variants.
  • recipient - recipient contact information. Requires firstName, lastName, email, and phone (E.164 format).
  • shippingAddress - the delivery address. Only countryCode (ISO 3166-1 alpha-2, uppercase) is required at the schema level. For physical variants, the full address is also required - see Behavior notes below.
Optional fields:
  • accountId - the Account placing the order. May be supplied here in the body or via the Snappy-Account-Id header (header takes precedence when both are provided).
  • idempotencyKey - a stable, caller-generated key (1-120 characters). Replaying the same request with the same key returns the original order without creating a duplicate.
  • tags - array of strings for grouping orders in reports (e.g. [“q4-campaign”, “vip”]).
  • metadata - key-value object for caller-supplied passthrough data. Up to 50 pairs; keys up to 40 chars; values up to 500 chars.
  • localizedFields.taxNumber - tax identification number to attach to the order. Required for orders shipping to CN, BR, AR, or CO. For swag products, also required for KR and IT. Both localizedFields and taxNumber may be omitted or null for all other countries and product types. We recommend adding a tax number field to your checkout UI and collecting it from users shipping to these countries. The field is accepted and ignored where it isn’t required, so we recommend sending it whenever you have it - more countries will be added, starting with CL, EC, PE, UY, and VE.
Behavior Notes:
  • The response is minimal: . Use GET /v3/orders/ to retrieve the full Order with line items, fulfillments, and tracking detail.
  • status is always active immediately after a successful placement.
  • The Billing Method is debited on successful order creation. If it has insufficient funds at the time of the request, the order is not processed (422).
  • Returns 422 for business-rule violations (insufficient funds, variant unavailable in the recipient’s country, variant not found, etc.).
  • Returns 404 if the referenced accountId, billingMethodId, or variantId does not exist or is not accessible to the calling Company.
  • Shipping address requirements depend on the variant type. For physical variants (variants where shippingRequired: true), the full address is required: address1, city, provinceCode, postalCode, and countryCode. address2 is optional but recommended. For digital variants (shippingRequired: false, e.g. gift cards and e-vouchers), countryCode alone is sufficient - no street/city/postal fields are needed since there’s no physical delivery.
  • Missing required address fields on a physical variant return a validation error.
  • Incomplete addresses on physical orders are a leading cause of fulfillment failures - we recommend validating with POST /orders/addresses/validate before placing the order.

Permissions

  • Requires: orders:create

Authorizations

X-Api-Key
string
header
required

Company Level Authentication

Include your API key in the X-Api-Key header for every request:

Headers

snappy-account-id
string
required

Required. Account identifier.

Minimum string length: 1
Example:

"acc123456"

Body

application/json

Request body for placing an order via the Direct Fulfillment integration. The account is identified by the Snappy-Account-Id header.

billingMethodId
string
required

The ID of the billing method that will pay for the order. Must belong to the specified account. Contact your Snappy account manager to retrieve your billing method IDs.

Pattern: ^[A-Za-z0-9]{8,}$
Example:

"87654321"

variantId
string
required

The ID of the specific product variant to order. Use GET /v3/products to browse available products and retrieve variant IDs.

Minimum string length: 1
Example:

"variant_abc123"

recipient
object
required

Order recipient's contact information.

Example:
shippingAddress
object
required

Physical shipping address for order delivery.

Example:
idempotencyKey
string

A unique key used to prevent duplicate orders. If a request with the same key has already succeeded for this company, the original order is returned without creating a duplicate. Use a stable, caller-generated identifier such as your internal order ID.

Required string length: 1 - 120
Example:

"order-2026-05-13-abc"

localizedFields
object | null

Optional country-specific order fields. May be null.

tags
string[]

Optional tags for grouping and filtering orders in reports.

Example:
metadata
object

Optional custom key-value pairs attached to the order. Use this to store additional information such as externalRecipientId for correlating with your internal systems. Maximum 50 pairs, keys up to 40 characters, values up to 500 characters.

Example:
externalId
string

Optional identifier from your system to correlate this order with your internal records.

Example:

"ext-order-12345"

Response

Order placed.

Successful response returned after an order is placed.

data
object
required

Details of the placed order.

Last modified on November 3, 2026