Create cash voucher
curl --request POST \
--url https://api.atlas.kitchen/admin/v1/cash_vouchers \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--header 'X-Merchant-Id: <api-key>' \
--data '
{
"cash_voucher": {
"label": "External gift voucher",
"code": "EXT-ABC123",
"value": 5000,
"expires_after": "2026-12-31",
"description": "Issued by external gift-card platform",
"unique": true,
"outlet_ids": [
1,
2
]
}
}
'import requests
url = "https://api.atlas.kitchen/admin/v1/cash_vouchers"
payload = { "cash_voucher": {
"label": "External gift voucher",
"code": "EXT-ABC123",
"value": 5000,
"expires_after": "2026-12-31",
"description": "Issued by external gift-card platform",
"unique": True,
"outlet_ids": [1, 2]
} }
headers = {
"X-Api-Key": "<api-key>",
"X-Merchant-Id": "<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>',
'X-Merchant-Id': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
cash_voucher: {
label: 'External gift voucher',
code: 'EXT-ABC123',
value: 5000,
expires_after: '2026-12-31',
description: 'Issued by external gift-card platform',
unique: true,
outlet_ids: [1, 2]
}
})
};
fetch('https://api.atlas.kitchen/admin/v1/cash_vouchers', 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.atlas.kitchen/admin/v1/cash_vouchers",
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([
'cash_voucher' => [
'label' => 'External gift voucher',
'code' => 'EXT-ABC123',
'value' => 5000,
'expires_after' => '2026-12-31',
'description' => 'Issued by external gift-card platform',
'unique' => true,
'outlet_ids' => [
1,
2
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Api-Key: <api-key>",
"X-Merchant-Id: <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.atlas.kitchen/admin/v1/cash_vouchers"
payload := strings.NewReader("{\n \"cash_voucher\": {\n \"label\": \"External gift voucher\",\n \"code\": \"EXT-ABC123\",\n \"value\": 5000,\n \"expires_after\": \"2026-12-31\",\n \"description\": \"Issued by external gift-card platform\",\n \"unique\": true,\n \"outlet_ids\": [\n 1,\n 2\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Api-Key", "<api-key>")
req.Header.Add("X-Merchant-Id", "<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.atlas.kitchen/admin/v1/cash_vouchers")
.header("X-Api-Key", "<api-key>")
.header("X-Merchant-Id", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"cash_voucher\": {\n \"label\": \"External gift voucher\",\n \"code\": \"EXT-ABC123\",\n \"value\": 5000,\n \"expires_after\": \"2026-12-31\",\n \"description\": \"Issued by external gift-card platform\",\n \"unique\": true,\n \"outlet_ids\": [\n 1,\n 2\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.atlas.kitchen/admin/v1/cash_vouchers")
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["X-Merchant-Id"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"cash_voucher\": {\n \"label\": \"External gift voucher\",\n \"code\": \"EXT-ABC123\",\n \"value\": 5000,\n \"expires_after\": \"2026-12-31\",\n \"description\": \"Issued by external gift-card platform\",\n \"unique\": true,\n \"outlet_ids\": [\n 1,\n 2\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"id": 123,
"label": "External gift voucher",
"description": "Issued by external gift-card platform",
"code": "EXT-ABC123",
"value": 5000,
"expires_after": "2026-12-31",
"unique": true,
"outlet_ids": [
1,
2
],
"status": "active",
"redemptions_count": 0,
"created_at": 1781615664,
"updated_at": 1781615664
}{
"type": "<string>",
"message": "<string>",
"error_hash": {}
}Create cash voucher
Creates a prepaid cash voucher that staff can redeem through the existing POS cash voucher flow.
Cash voucher values are monetary amounts in minor currency units (cents). For example, 5000 means $50.00. Voucher codes are normalized by Atlas before storage.
outlet_ids controls which outlet pickers show the voucher. It does not block redemption at other outlets when staff enter the voucher code manually.
Atlas does not emit a standalone cash voucher redemption webhook from this endpoint. External issuers that need close-the-loop redemption callbacks should use a future dedicated redemption event or an order webhook payload that explicitly includes voucher payment details.
POST
/
cash_vouchers
Create cash voucher
curl --request POST \
--url https://api.atlas.kitchen/admin/v1/cash_vouchers \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--header 'X-Merchant-Id: <api-key>' \
--data '
{
"cash_voucher": {
"label": "External gift voucher",
"code": "EXT-ABC123",
"value": 5000,
"expires_after": "2026-12-31",
"description": "Issued by external gift-card platform",
"unique": true,
"outlet_ids": [
1,
2
]
}
}
'import requests
url = "https://api.atlas.kitchen/admin/v1/cash_vouchers"
payload = { "cash_voucher": {
"label": "External gift voucher",
"code": "EXT-ABC123",
"value": 5000,
"expires_after": "2026-12-31",
"description": "Issued by external gift-card platform",
"unique": True,
"outlet_ids": [1, 2]
} }
headers = {
"X-Api-Key": "<api-key>",
"X-Merchant-Id": "<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>',
'X-Merchant-Id': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
cash_voucher: {
label: 'External gift voucher',
code: 'EXT-ABC123',
value: 5000,
expires_after: '2026-12-31',
description: 'Issued by external gift-card platform',
unique: true,
outlet_ids: [1, 2]
}
})
};
fetch('https://api.atlas.kitchen/admin/v1/cash_vouchers', 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.atlas.kitchen/admin/v1/cash_vouchers",
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([
'cash_voucher' => [
'label' => 'External gift voucher',
'code' => 'EXT-ABC123',
'value' => 5000,
'expires_after' => '2026-12-31',
'description' => 'Issued by external gift-card platform',
'unique' => true,
'outlet_ids' => [
1,
2
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Api-Key: <api-key>",
"X-Merchant-Id: <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.atlas.kitchen/admin/v1/cash_vouchers"
payload := strings.NewReader("{\n \"cash_voucher\": {\n \"label\": \"External gift voucher\",\n \"code\": \"EXT-ABC123\",\n \"value\": 5000,\n \"expires_after\": \"2026-12-31\",\n \"description\": \"Issued by external gift-card platform\",\n \"unique\": true,\n \"outlet_ids\": [\n 1,\n 2\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Api-Key", "<api-key>")
req.Header.Add("X-Merchant-Id", "<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.atlas.kitchen/admin/v1/cash_vouchers")
.header("X-Api-Key", "<api-key>")
.header("X-Merchant-Id", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"cash_voucher\": {\n \"label\": \"External gift voucher\",\n \"code\": \"EXT-ABC123\",\n \"value\": 5000,\n \"expires_after\": \"2026-12-31\",\n \"description\": \"Issued by external gift-card platform\",\n \"unique\": true,\n \"outlet_ids\": [\n 1,\n 2\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.atlas.kitchen/admin/v1/cash_vouchers")
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["X-Merchant-Id"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"cash_voucher\": {\n \"label\": \"External gift voucher\",\n \"code\": \"EXT-ABC123\",\n \"value\": 5000,\n \"expires_after\": \"2026-12-31\",\n \"description\": \"Issued by external gift-card platform\",\n \"unique\": true,\n \"outlet_ids\": [\n 1,\n 2\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"id": 123,
"label": "External gift voucher",
"description": "Issued by external gift-card platform",
"code": "EXT-ABC123",
"value": 5000,
"expires_after": "2026-12-31",
"unique": true,
"outlet_ids": [
1,
2
],
"status": "active",
"redemptions_count": 0,
"created_at": 1781615664,
"updated_at": 1781615664
}{
"type": "<string>",
"message": "<string>",
"error_hash": {}
}Authorizations
Your API key provided during onboarding. Example c2fb5ae6ea99c37d...
Your numeric merchant ID. Example 1
Body
application/json
Show child attributes
Show child attributes
Response
Cash voucher created
Atlas cash voucher ID.
Example:
123
Display label for the voucher.
Example:
"External gift voucher"
Optional note or campaign description for the voucher.
Example:
"Issued by external gift-card platform"
Customer-facing redemption code. Atlas stores codes in uppercase without whitespace.
Example:
"EXT-ABC123"
Voucher value in minor currency units (cents). For example, 5000 means $50.00.
Example:
5000
Last valid service date for redemption, in ISO 8601 date format. A voucher with expires_after: 2026-12-31 is redeemable on 2026-12-31 and expires on 2027-01-01.
Example:
"2026-12-31"
Whether the voucher can only be redeemed once. Defaults to true when omitted on create.
Example:
true
Outlet IDs where the POS picker shows this voucher. An empty array means all outlets. This setting does not block manual code redemption at other outlets.
Example:
[1, 2]
Computed voucher state. expired wins when expires_after is in the past; redeemed applies to non-expired unique vouchers with a captured redemption; otherwise the voucher is active.
Available options:
active, expired, redeemed Example:
"active"
Number of redeemed voucher units, excluding fully refunded cash voucher payments.
Example:
0
Unix epoch timestamp in seconds.
Example:
1781615664
Unix epoch timestamp in seconds.
Example:
1781615664
Was this page helpful?