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

X-Api-Key

string

header

required

Your API key provided during onboarding. Example c2fb5ae6ea99c37d...

X-Merchant-Id

string

header

required

Your numeric merchant ID. Example 1

Body

application/json

cash_voucher

object

required

Show child attributes

Response

Cash voucher created

integer

Atlas cash voucher ID.

Example:

123

label

string

Display label for the voucher.

Example:

"External gift voucher"

description

string | null

Optional note or campaign description for the voucher.

Example:

"Issued by external gift-card platform"

code

string

Customer-facing redemption code. Atlas stores codes in uppercase without whitespace.

Example:

"EXT-ABC123"

value

integer

Voucher value in minor currency units (cents). For example, 5000 means $50.00.

Example:

5000

expires_after

string<date>

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"

unique

boolean

Whether the voucher can only be redeemed once. Defaults to true when omitted on create.

Example:

true

outlet_ids

integer[]

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]

status

enum<string>

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"

redemptions_count

integer

Number of redeemed voucher units, excluding fully refunded cash voucher payments.

Example:

0

created_at

integer

Unix epoch timestamp in seconds.

Example:

1781615664

updated_at

integer

Unix epoch timestamp in seconds.

Example:

1781615664

⌘I

Storefront API

Admin API

Webhooks

Create cash voucher

Authorizations

Body

Response