Orders & Dispatch

Create New Order

Creates a single gift-card order against your integration wallet.

How to call

Method: POST
URL: {server}/api/v1/business/orders
Headers: X-API-Key, optional Idempotency-Key (recommended for retries).
Body: JSON matching CreateOrderRequest (productCode, merchant, currency, valuePurchased, optional recipient fields).

Responses

201 when the order is created synchronously (or idempotent replay).
202 when async processing is enabled (orderRequestId, status: queued); poll GET /api/v1/business/orders/order-requests/{id}.
402 when the wallet balance (after holds) is insufficient.

POST

api

business

orders

Create New Order

curl --request POST \
  --url https://api-stage.ugift.me/api/v1/business/orders \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "productCode": "<string>",
  "merchant": "<string>",
  "currency": "GBP",
  "valuePurchased": 123,
  "recipientEmail": "jsmith@example.com",
  "recipientName": "<string>",
  "giftMessage": "<string>"
}
'

import requests

url = "https://api-stage.ugift.me/api/v1/business/orders"

payload = {
    "productCode": "<string>",
    "merchant": "<string>",
    "currency": "GBP",
    "valuePurchased": 123,
    "recipientEmail": "jsmith@example.com",
    "recipientName": "<string>",
    "giftMessage": "<string>"
}
headers = {
    "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: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    productCode: '<string>',
    merchant: '<string>',
    currency: 'GBP',
    valuePurchased: 123,
    recipientEmail: 'jsmith@example.com',
    recipientName: '<string>',
    giftMessage: '<string>'
  })
};

fetch('https://api-stage.ugift.me/api/v1/business/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-stage.ugift.me/api/v1/business/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([
    'productCode' => '<string>',
    'merchant' => '<string>',
    'currency' => 'GBP',
    'valuePurchased' => 123,
    'recipientEmail' => 'jsmith@example.com',
    'recipientName' => '<string>',
    'giftMessage' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$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-stage.ugift.me/api/v1/business/orders"

	payload := strings.NewReader("{\n  \"productCode\": \"<string>\",\n  \"merchant\": \"<string>\",\n  \"currency\": \"GBP\",\n  \"valuePurchased\": 123,\n  \"recipientEmail\": \"jsmith@example.com\",\n  \"recipientName\": \"<string>\",\n  \"giftMessage\": \"<string>\"\n}")

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

	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-stage.ugift.me/api/v1/business/orders")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"productCode\": \"<string>\",\n  \"merchant\": \"<string>\",\n  \"currency\": \"GBP\",\n  \"valuePurchased\": 123,\n  \"recipientEmail\": \"jsmith@example.com\",\n  \"recipientName\": \"<string>\",\n  \"giftMessage\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-stage.ugift.me/api/v1/business/orders")

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"productCode\": \"<string>\",\n  \"merchant\": \"<string>\",\n  \"currency\": \"GBP\",\n  \"valuePurchased\": 123,\n  \"recipientEmail\": \"jsmith@example.com\",\n  \"recipientName\": \"<string>\",\n  \"giftMessage\": \"<string>\"\n}"

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

{
  "_id": "65b0d1e2f3a4b56789012345",
  "productCode": "AMAZON_UK_STD",
  "merchant": {
    "name": "Amazon UK",
    "distributionMethod": "EMAIL",
    "voucherCode": "XXXX-XXXX-XXXX-XXXX",
    "redemptionUrl": "https://www.amazon.co.uk/gc/redeem"
  },
  "currency": "GBP",
  "valuePurchased": 50,
  "status": "active",
  "isPaid": true,
  "isActive": true,
  "usageLimit": 1,
  "giftOrder": {
    "message": "Thanks for being a great customer!",
    "recipientEmail": "alex@example.com",
    "recipientName": "Alex"
  },
  "transactionId": "txn_01HZZ9K2M4P8Q6R7S8T9V0W1X",
  "createdAt": "2025-04-12T14:22:10.000Z",
  "updatedAt": "2025-04-12T14:22:11.000Z",
  "imageUrl": "https://cdn.ugift.me/products/amazon-uk-card.png"
}

Authorizations

X-API-Key

string

header

required

Your UGiftMe API key for authentication.

Format: Secure API key (e.g., <your-api-key>)

Required: All endpoints require this header

Example: X-API-Key: <your-api-key>

Headers

Idempotency-Key

string

Body

application/json

productCode

string

required

merchant

string

required

currency

string

required

Example:

"GBP"

valuePurchased

number

required

recipientEmail

string<email>

recipientName

string

giftMessage

string

Response

Order created (sync path or idempotent replay)

Account-facing order shape. List/search responses include imageUrl from withImageUrl; synchronous 201 creates may include populated product instead of imageUrl.

_id

string

Example:

"65b0d1e2f3a4b56789012345"

productCode

string

Example:

"AMAZON_UK_STD"

product

object

Populated product on synchronous 201 order responses.

Show child attributes

Example:

{
  "imageUrl": "https://cdn.ugift.me/products/amazon-uk-card.png",
  "merchant": "Amazon UK",
  "productCode": "AMAZON_UK_STD"
}

merchant

object

currency

string

Example:

"GBP"

valuePurchased

number

Example:

50

status

string

Example:

"active"

isPaid

boolean

Example:

true

isActive

boolean

Example:

true

isActivated

boolean

Example:

false

usageLimit

number

Example:

1

giftOrder

object

transactionId

string

Example:

"txn_01HZZ9K2M4P8Q6R7S8T9V0W1X"

createdAt

string<date-time>

Example:

"2025-04-12T14:22:10.000Z"

updatedAt

string<date-time>

Example:

"2025-04-12T14:22:11.000Z"

imageUrl

string

Example:

"https://cdn.ugift.me/products/amazon-uk-card.png"

previousUserId

string

Present on some gift/recipient flows.

Create New Order

curl --request POST \
  --url https://api-stage.ugift.me/api/v1/business/orders \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "productCode": "<string>",
  "merchant": "<string>",
  "currency": "GBP",
  "valuePurchased": 123,
  "recipientEmail": "jsmith@example.com",
  "recipientName": "<string>",
  "giftMessage": "<string>"
}
'

import requests

url = "https://api-stage.ugift.me/api/v1/business/orders"

payload = {
    "productCode": "<string>",
    "merchant": "<string>",
    "currency": "GBP",
    "valuePurchased": 123,
    "recipientEmail": "jsmith@example.com",
    "recipientName": "<string>",
    "giftMessage": "<string>"
}
headers = {
    "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: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    productCode: '<string>',
    merchant: '<string>',
    currency: 'GBP',
    valuePurchased: 123,
    recipientEmail: 'jsmith@example.com',
    recipientName: '<string>',
    giftMessage: '<string>'
  })
};

fetch('https://api-stage.ugift.me/api/v1/business/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-stage.ugift.me/api/v1/business/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([
    'productCode' => '<string>',
    'merchant' => '<string>',
    'currency' => 'GBP',
    'valuePurchased' => 123,
    'recipientEmail' => 'jsmith@example.com',
    'recipientName' => '<string>',
    'giftMessage' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$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-stage.ugift.me/api/v1/business/orders"

	payload := strings.NewReader("{\n  \"productCode\": \"<string>\",\n  \"merchant\": \"<string>\",\n  \"currency\": \"GBP\",\n  \"valuePurchased\": 123,\n  \"recipientEmail\": \"jsmith@example.com\",\n  \"recipientName\": \"<string>\",\n  \"giftMessage\": \"<string>\"\n}")

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

	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-stage.ugift.me/api/v1/business/orders")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"productCode\": \"<string>\",\n  \"merchant\": \"<string>\",\n  \"currency\": \"GBP\",\n  \"valuePurchased\": 123,\n  \"recipientEmail\": \"jsmith@example.com\",\n  \"recipientName\": \"<string>\",\n  \"giftMessage\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-stage.ugift.me/api/v1/business/orders")

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"productCode\": \"<string>\",\n  \"merchant\": \"<string>\",\n  \"currency\": \"GBP\",\n  \"valuePurchased\": 123,\n  \"recipientEmail\": \"jsmith@example.com\",\n  \"recipientName\": \"<string>\",\n  \"giftMessage\": \"<string>\"\n}"

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

{
  "_id": "65b0d1e2f3a4b56789012345",
  "productCode": "AMAZON_UK_STD",
  "merchant": {
    "name": "Amazon UK",
    "distributionMethod": "EMAIL",
    "voucherCode": "XXXX-XXXX-XXXX-XXXX",
    "redemptionUrl": "https://www.amazon.co.uk/gc/redeem"
  },
  "currency": "GBP",
  "valuePurchased": 50,
  "status": "active",
  "isPaid": true,
  "isActive": true,
  "usageLimit": 1,
  "giftOrder": {
    "message": "Thanks for being a great customer!",
    "recipientEmail": "alex@example.com",
    "recipientName": "Alex"
  },
  "transactionId": "txn_01HZZ9K2M4P8Q6R7S8T9V0W1X",
  "createdAt": "2025-04-12T14:22:10.000Z",
  "updatedAt": "2025-04-12T14:22:11.000Z",
  "imageUrl": "https://cdn.ugift.me/products/amazon-uk-card.png"
}

Authentication

Product Catalog

Orders & Dispatch

Financials

Webhooks

Outbound webhook events

Create New Order

Authorizations

Headers

Body

Response