This endpoint creates a new order with a list of recipients who will receive the vouchers via email. Instead of specifying a quantity, you provide a list of recipients with their first name, last name, and email address. Each recipient will receive one voucher. The vouchers will be delivered to the recipients' email addresses.

Request

Method: POST
URL: /v2/orders/recipients
Body:

{
  "reference": "123456789",
  "productCode": "SGF_4",
  "amount": 1000,
  "recipients": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]"
    },
    {
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "[email protected]"
    }
  ],
  "templateId": 10041,
  "narration": "Birthday gift vouchers"
}

Field Descriptions:

• reference (string, required, length ≥ 1) – Your own unique order number. Used to check the order status later. Defaults to 123456789.
• productCode (string, required, length ≥ 1) – Code of the product being purchased. Obtainable from the Get Available Products endpoint. Defaults to SGF_4.
• amount (double, required) – Price per voucher. Defaults to 1000.
• recipients (array, required) – List of recipients who will receive the vouchers. At least one recipient is required.
  • firstName (string, required) – Recipient's first name.
  • lastName (string, required) – Recipient's last name.
  • email (string, required) – Recipient's email address. Must be a valid email format.
• templateId (int, required) – Template ID for customizing the voucher appearance. Obtainable from the Get Client Templates endpoint. Must be a valid template that belongs to your business or a global template.
• narration (string | null, optional) – Custom message/narration for the order. If not provided, defaults to "{ProductName} vouchers".

Responses

200 OK – Successful

Field Descriptions:

• data.orderNumber (string) – SureGifts order reference number.
• data.reference (string) – The client-provided reference used to create the order.
• data.status (string) – Current voucher status. Possible values: FAILED, CANCELED, COMPLETED, PARTIALLY_COMPLETED, PROCESSING.
• data.vouchers (array) – List of vouchers created from the order. Note: The voucher schema varies based on order type.
  • value (double) – Initial voucher value.
  • serial (number) – Voucher serial number.
  • code (string) – Voucher code. Included for Recipient orders only (not exposed to API clients).
  • pin (string) – Voucher redemption PIN. Included for Recipient orders only (not exposed to API clients).
  • expiryDate (date-time | null) – Voucher expiry date. Included for Recipient orders only.
  • status (string | null) – Item delivery status. Possible values: FAILED, CANCELED, DELIVERED, PROCESSING. Included for Recipient orders only.
  • firstName (string | null) – Recipient's first name. Included for Recipient orders only.
  • lastName (string | null) – Recipient's last name. Included for Recipient orders only.
  • email (string | null) – Recipient's email address. Included for Recipient orders only.
• statusCode (string) – Request status code ("00" indicates success).
• message (string | null) – Human-readable description of the status code.

Note: Vouchers are returned in the response and also delivered to the recipients' email addresses.

Example – Completed

{
    "data": {
        "orderNumber": "002104",
        "reference": "784",
        "status": "COMPLETED",
        "vouchers": [
            {
                "value": 1000.00,
                "expiryDate": "2026-08-14T19:53:26.320451Z",
                "pin": "0000",
                "code": "262256943944",
                "serial": 300002722,
                "status": "DELIVERED",
                "firstName": "John",
                "lastName": "Doe",
                "email": "[email protected]"
            }
        ]
    },
    "statusCode": "00",
    "message": "Successful"
}

Example – Processing

{
    "data": {
        "orderNumber": "002105",
        "reference": "569",
        "status": "PROCESSING"
    },
    "statusCode": "00",
    "message": "Successful"
}

Other Status Codes

Non-00 status codes follow the definitions provided in the SureGifts API documentation.

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

500 Internal Server Error

Internal Server Error

Example cURL Request

curl -X POST \
  'https://{baseUrl}/v2/orders/recipients' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "reference": "123456789",
    "productCode": "SGF_4",
    "amount": 1000,
    "recipients": [
      {
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]"
      }
    ],
    "templateId": "10041",
    "narration": "Birthday gift vouchers"
  }'