Place an order - v3

curl --request POST \
  --url https://api.snappy.com/public-api/v3/orders \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --header 'snappy-account-id: <snappy-account-id>' \
  --data '
{
  "billingMethodId": "87654321",
  "variantId": "variant_abc123",
  "recipient": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+12133734253"
  },
  "shippingAddress": {
    "address1": "123 Main St",
    "address2": "Apt 4B",
    "city": "New York",
    "provinceCode": "NY",
    "postalCode": "10001",
    "countryCode": "US"
  },
  "idempotencyKey": "order-2026-05-13-abc",
  "metadata": {
    "externalRecipientId": "crm-user-987"
  }
}
'

import requests

url = "https://api.snappy.com/public-api/v3/orders"

payload = {
    "billingMethodId": "87654321",
    "variantId": "variant_abc123",
    "recipient": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "phone": "+12133734253"
    },
    "shippingAddress": {
        "address1": "123 Main St",
        "address2": "Apt 4B",
        "city": "New York",
        "provinceCode": "NY",
        "postalCode": "10001",
        "countryCode": "US"
    },
    "idempotencyKey": "order-2026-05-13-abc",
    "metadata": { "externalRecipientId": "crm-user-987" }
}
headers = {
    "snappy-account-id": "<snappy-account-id>",
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'snappy-account-id': '<snappy-account-id>',
    'X-Api-Key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    billingMethodId: '87654321',
    variantId: 'variant_abc123',
    recipient: {
      firstName: 'John',
      lastName: 'Doe',
      email: 'john.doe@example.com',
      phone: '+12133734253'
    },
    shippingAddress: {
      address1: '123 Main St',
      address2: 'Apt 4B',
      city: 'New York',
      provinceCode: 'NY',
      postalCode: '10001',
      countryCode: 'US'
    },
    idempotencyKey: 'order-2026-05-13-abc',
    metadata: {externalRecipientId: 'crm-user-987'}
  })
};

fetch('https://api.snappy.com/public-api/v3/orders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.snappy.com/public-api/v3/orders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'billingMethodId' => '87654321',
    'variantId' => 'variant_abc123',
    'recipient' => [
        'firstName' => 'John',
        'lastName' => 'Doe',
        'email' => 'john.doe@example.com',
        'phone' => '+12133734253'
    ],
    'shippingAddress' => [
        'address1' => '123 Main St',
        'address2' => 'Apt 4B',
        'city' => 'New York',
        'provinceCode' => 'NY',
        'postalCode' => '10001',
        'countryCode' => 'US'
    ],
    'idempotencyKey' => 'order-2026-05-13-abc',
    'metadata' => [
        'externalRecipientId' => 'crm-user-987'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Api-Key: <api-key>",
    "snappy-account-id: <snappy-account-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.snappy.com/public-api/v3/orders"

	payload := strings.NewReader("{\n  \"billingMethodId\": \"87654321\",\n  \"variantId\": \"variant_abc123\",\n  \"recipient\": {\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\",\n    \"email\": \"john.doe@example.com\",\n    \"phone\": \"+12133734253\"\n  },\n  \"shippingAddress\": {\n    \"address1\": \"123 Main St\",\n    \"address2\": \"Apt 4B\",\n    \"city\": \"New York\",\n    \"provinceCode\": \"NY\",\n    \"postalCode\": \"10001\",\n    \"countryCode\": \"US\"\n  },\n  \"idempotencyKey\": \"order-2026-05-13-abc\",\n  \"metadata\": {\n    \"externalRecipientId\": \"crm-user-987\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("snappy-account-id", "<snappy-account-id>")
	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.snappy.com/public-api/v3/orders")
  .header("snappy-account-id", "<snappy-account-id>")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"billingMethodId\": \"87654321\",\n  \"variantId\": \"variant_abc123\",\n  \"recipient\": {\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\",\n    \"email\": \"john.doe@example.com\",\n    \"phone\": \"+12133734253\"\n  },\n  \"shippingAddress\": {\n    \"address1\": \"123 Main St\",\n    \"address2\": \"Apt 4B\",\n    \"city\": \"New York\",\n    \"provinceCode\": \"NY\",\n    \"postalCode\": \"10001\",\n    \"countryCode\": \"US\"\n  },\n  \"idempotencyKey\": \"order-2026-05-13-abc\",\n  \"metadata\": {\n    \"externalRecipientId\": \"crm-user-987\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.snappy.com/public-api/v3/orders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["snappy-account-id"] = '<snappy-account-id>'
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"billingMethodId\": \"87654321\",\n  \"variantId\": \"variant_abc123\",\n  \"recipient\": {\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\",\n    \"email\": \"john.doe@example.com\",\n    \"phone\": \"+12133734253\"\n  },\n  \"shippingAddress\": {\n    \"address1\": \"123 Main St\",\n    \"address2\": \"Apt 4B\",\n    \"city\": \"New York\",\n    \"provinceCode\": \"NY\",\n    \"postalCode\": \"10001\",\n    \"countryCode\": \"US\"\n  },\n  \"idempotencyKey\": \"order-2026-05-13-abc\",\n  \"metadata\": {\n    \"externalRecipientId\": \"crm-user-987\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "G7nR4bD9mK",
    "status": "active",
    "trackingLink": "https://gift.snappy.com/choose/G7nR4bD9mK?utm_source=l&utm_medium=i&utm_campaign=l2fX39ZvaM"
  }
}

{
  "message": "Product not found.",
  "errorCode": "404_PROD_001",
  "errors": [
    {
      "message": "Product with id 'q1w2e3r4t5' was not found",
      "path": "pathParameters.productId",
      "errorCode": "404_PROD_001"
    }
  ]
}

{
  "message": "Product not found.",
  "errorCode": "404_PROD_001",
  "errors": [
    {
      "message": "Product with id 'q1w2e3r4t5' was not found",
      "path": "pathParameters.productId",
      "errorCode": "404_PROD_001"
    }
  ]
}

{
  "message": "Product not found.",
  "errorCode": "404_PROD_001",
  "errors": [
    {
      "message": "Product with id 'q1w2e3r4t5' was not found",
      "path": "pathParameters.productId",
      "errorCode": "404_PROD_001"
    }
  ]
}

{
  "message": "Product not found.",
  "errorCode": "404_PROD_001",
  "errors": [
    {
      "message": "Product with id 'q1w2e3r4t5' was not found",
      "path": "pathParameters.productId",
      "errorCode": "404_PROD_001"
    }
  ]
}

Orders

Place order

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.

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 - physical shipping address. Requires address1, city, provinceCode (2-3 uppercase letters), postalCode, and countryCode (ISO 3166-1 alpha-2).
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.

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).
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.
Snappy-Company-Id header - optional company scoping.

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.
address2 on the shipping address is optional but recommended (apartment, suite, floor, etc.) - incomplete addresses are a leading cause of fulfillment failures.

Permissions

Requires: gifts:create or orders:create

POST

orders

Place an order - v3

curl --request POST \
  --url https://api.snappy.com/public-api/v3/orders \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --header 'snappy-account-id: <snappy-account-id>' \
  --data '
{
  "billingMethodId": "87654321",
  "variantId": "variant_abc123",
  "recipient": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+12133734253"
  },
  "shippingAddress": {
    "address1": "123 Main St",
    "address2": "Apt 4B",
    "city": "New York",
    "provinceCode": "NY",
    "postalCode": "10001",
    "countryCode": "US"
  },
  "idempotencyKey": "order-2026-05-13-abc",
  "metadata": {
    "externalRecipientId": "crm-user-987"
  }
}
'

import requests

url = "https://api.snappy.com/public-api/v3/orders"

payload = {
    "billingMethodId": "87654321",
    "variantId": "variant_abc123",
    "recipient": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "phone": "+12133734253"
    },
    "shippingAddress": {
        "address1": "123 Main St",
        "address2": "Apt 4B",
        "city": "New York",
        "provinceCode": "NY",
        "postalCode": "10001",
        "countryCode": "US"
    },
    "idempotencyKey": "order-2026-05-13-abc",
    "metadata": { "externalRecipientId": "crm-user-987" }
}
headers = {
    "snappy-account-id": "<snappy-account-id>",
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'snappy-account-id': '<snappy-account-id>',
    'X-Api-Key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    billingMethodId: '87654321',
    variantId: 'variant_abc123',
    recipient: {
      firstName: 'John',
      lastName: 'Doe',
      email: 'john.doe@example.com',
      phone: '+12133734253'
    },
    shippingAddress: {
      address1: '123 Main St',
      address2: 'Apt 4B',
      city: 'New York',
      provinceCode: 'NY',
      postalCode: '10001',
      countryCode: 'US'
    },
    idempotencyKey: 'order-2026-05-13-abc',
    metadata: {externalRecipientId: 'crm-user-987'}
  })
};

fetch('https://api.snappy.com/public-api/v3/orders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.snappy.com/public-api/v3/orders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'billingMethodId' => '87654321',
    'variantId' => 'variant_abc123',
    'recipient' => [
        'firstName' => 'John',
        'lastName' => 'Doe',
        'email' => 'john.doe@example.com',
        'phone' => '+12133734253'
    ],
    'shippingAddress' => [
        'address1' => '123 Main St',
        'address2' => 'Apt 4B',
        'city' => 'New York',
        'provinceCode' => 'NY',
        'postalCode' => '10001',
        'countryCode' => 'US'
    ],
    'idempotencyKey' => 'order-2026-05-13-abc',
    'metadata' => [
        'externalRecipientId' => 'crm-user-987'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Api-Key: <api-key>",
    "snappy-account-id: <snappy-account-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.snappy.com/public-api/v3/orders"

	payload := strings.NewReader("{\n  \"billingMethodId\": \"87654321\",\n  \"variantId\": \"variant_abc123\",\n  \"recipient\": {\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\",\n    \"email\": \"john.doe@example.com\",\n    \"phone\": \"+12133734253\"\n  },\n  \"shippingAddress\": {\n    \"address1\": \"123 Main St\",\n    \"address2\": \"Apt 4B\",\n    \"city\": \"New York\",\n    \"provinceCode\": \"NY\",\n    \"postalCode\": \"10001\",\n    \"countryCode\": \"US\"\n  },\n  \"idempotencyKey\": \"order-2026-05-13-abc\",\n  \"metadata\": {\n    \"externalRecipientId\": \"crm-user-987\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("snappy-account-id", "<snappy-account-id>")
	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.snappy.com/public-api/v3/orders")
  .header("snappy-account-id", "<snappy-account-id>")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"billingMethodId\": \"87654321\",\n  \"variantId\": \"variant_abc123\",\n  \"recipient\": {\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\",\n    \"email\": \"john.doe@example.com\",\n    \"phone\": \"+12133734253\"\n  },\n  \"shippingAddress\": {\n    \"address1\": \"123 Main St\",\n    \"address2\": \"Apt 4B\",\n    \"city\": \"New York\",\n    \"provinceCode\": \"NY\",\n    \"postalCode\": \"10001\",\n    \"countryCode\": \"US\"\n  },\n  \"idempotencyKey\": \"order-2026-05-13-abc\",\n  \"metadata\": {\n    \"externalRecipientId\": \"crm-user-987\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.snappy.com/public-api/v3/orders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["snappy-account-id"] = '<snappy-account-id>'
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"billingMethodId\": \"87654321\",\n  \"variantId\": \"variant_abc123\",\n  \"recipient\": {\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\",\n    \"email\": \"john.doe@example.com\",\n    \"phone\": \"+12133734253\"\n  },\n  \"shippingAddress\": {\n    \"address1\": \"123 Main St\",\n    \"address2\": \"Apt 4B\",\n    \"city\": \"New York\",\n    \"provinceCode\": \"NY\",\n    \"postalCode\": \"10001\",\n    \"countryCode\": \"US\"\n  },\n  \"idempotencyKey\": \"order-2026-05-13-abc\",\n  \"metadata\": {\n    \"externalRecipientId\": \"crm-user-987\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "G7nR4bD9mK",
    "status": "active",
    "trackingLink": "https://gift.snappy.com/choose/G7nR4bD9mK?utm_source=l&utm_medium=i&utm_campaign=l2fX39ZvaM"
  }
}

{
  "message": "Product not found.",
  "errorCode": "404_PROD_001",
  "errors": [
    {
      "message": "Product with id 'q1w2e3r4t5' was not found",
      "path": "pathParameters.productId",
      "errorCode": "404_PROD_001"
    }
  ]
}

{
  "message": "Product not found.",
  "errorCode": "404_PROD_001",
  "errors": [
    {
      "message": "Product with id 'q1w2e3r4t5' was not found",
      "path": "pathParameters.productId",
      "errorCode": "404_PROD_001"
    }
  ]
}

{
  "message": "Product not found.",
  "errorCode": "404_PROD_001",
  "errors": [
    {
      "message": "Product with id 'q1w2e3r4t5' was not found",
      "path": "pathParameters.productId",
      "errorCode": "404_PROD_001"
    }
  ]
}

{
  "message": "Product not found.",
  "errorCode": "404_PROD_001",
  "errors": [
    {
      "message": "Product with id 'q1w2e3r4t5' was not found",
      "path": "pathParameters.productId",
      "errorCode": "404_PROD_001"
    }
  ]
}

Authorizations

X-Api-Key

string

header

required

Company Level Authentication

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

X-Api-Key: YOUR_API_KEY

Headers

snappy-account-id

string

required

Account identifier.

Example:

"acc123456"

snappy-company-id

string

Optional company identifier.

Example:

"cmp123456"

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.

Show child attributes

Example:

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+12133734253"
}

shippingAddress

object

required

Physical shipping address for order delivery.

Show child attributes

Example:

{
  "address1": "123 Main St",
  "address2": "Apt 4B",
  "city": "New York",
  "provinceCode": "NY",
  "postalCode": "10001",
  "countryCode": "US"
}

idempotencyKey

string

required

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"

Response

Order placed.

Successful response returned after an order is placed.

data

object

required

Details of the placed order.

Show child attributes

Last modified on June 17, 2026

Orders API: Place, Track, and Manage Orders

Get orders

Authentication

Marketplace

Gifting

Administration

Place order

Required fields:

Optional fields:

Behavior Notes:

Permissions

Authorizations

Company Level Authentication

Headers

Body

Response