This endpoint creates a new order for a specified product. You must specify the product code, purchase amount, quantity, a unique reference, and an optional preferred security PIN for the voucher. On successful creation, the order status and any generated vouchers will be returned. Depending on the processing state, the order status may be COMPLETED (vouchers immediately available) or PROCESSING (vouchers will be delivered later).

Request

Method: POST
URL: /v2/orders
Body:

{
  "reference": "123456789",
  "productCode": "SGF_4",
  "amount": 1000,
  "quantity": 1,
  "pin": "0000"
}

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 item ordered. Defaults to 1000.
• quantity (int32, required) – Number of vouchers to be created. Defaults to 1.
• pin (string | null, optional) – Preferred 4-digit PIN for the voucher. If omitted, a random PIN will be created. Defaults to 0000.

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 | null) – List of vouchers created from the order. Not included when Download orders have status PROCESSING. The voucher schema varies based on order type.
  • value (double) – Initial voucher value.
  • serial (number) – Voucher serial number.
  • code (string) – Voucher code. Included for Download orders only.
  • pin (string) – Voucher redemption PIN. Included for Download orders only.
  • expiryDate (date-time | null) – Voucher expiry date. Technically, vouchers don't expire; the system automatically extends the date by 1 year. Included for Download orders only.
  • status (string | null) – Item delivery status. Possible values: FAILED, CANCELED, DELIVERED, PROCESSING. Null for Download orders.
  • firstName (string | null) – Recipient first name. Null for Download orders.
  • lastName (string | null) – Recipient last name. Null for Download orders.
  • email (string | null) – Recipient email address. Null for Download orders.
• statusCode (string) – Request status code ("00" indicates success).
• message (string | null) – Human-readable description of the status code.

Example – Completed

{
    "data": {
        "orderNumber": "002104",
        "reference": "784",
        "status": "COMPLETED",
        "vouchers": [
            {
                "value": 500.00,
                "expiryDate": "2026-08-14T19:53:26.320451Z",
                "pin": "0000",
                "code": "262256943944",
                "serial": 300002722
            }
        ]
    },
    "statusCode": "00",
    "message": "Successful"
}

Example – Processing

Note: When a Download order has status PROCESSING, the vouchers array is not included in the response.

{
    "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' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "reference": "123456789",
    "productCode": "SGF_4",
    "amount": 1000,
    "quantity": 1,
    "pin": "0000"
  }'