Vouchers

Our base domain URL is https://api.dotapparel.io.

Create gift voucher in Apparel21

post

Scope: maintainer and above

This endpoint allows you to create a gift voucher in Apparel21. The gift voucher is a digital voucher that can be sent to customers via email, containing a pin number that can be used for making purchases. Before using this endpoint, ensure that the necessary configurations are set up in both DotApparel and Apparel21.

Requirements:

1. Gift Card SKU IDX: Make sure the SKU IDX for the gift card has been set up in DotApparel. This ensures that the appropriate product is associated with the gift voucher.

2. Voucher Type: Ensure that the voucher type has been configured in DotApparel. This specifies the specific type of gift voucher being created.

3. Gift Voucher Function: Confirm with your merchant that the gift voucher function has been properly set up in Apparel21. This ensures that the system can automatically send out an email containing the digital gift voucher and pin number to the customer.

Authorizations

Header parameters

X-DotApparel-NamestringRequired

shopstringRequired

Body

gatewaystringRequired

To obtain the names of all available payment gateways, you can make a GET request to the "/order/gateways" endpoint. In order to determine the appropriate gateway for this specific request, please get in touch with your merchant.

Example: shopify

messagestringOptional

The message that are sent to receiver

Example: Happy birthday!

orderNumberstringOptional

If an orderNumber is provided, it will be recognised as the Customer Order Number within the Apparel21. However, if the field is left empty, the API will automatically generate a unique order number.

Example: #1001

pricenumberRequired

The unit price of the gift card

Example: 100

receiverEmailstringRequired

The gift voucher receiver's email address

Example: [e-mail]

receiverNamestringRequired

The gift voucher receiver's name

Example: Smith James

senderEmailstringRequired

The email field is mandatory.

Example: [e-mail]

senderMobilestringOptional

Mobile Phone

Example: [phone]

senderNamestringRequired

The gift voucher sender's name

Example: John Williams

subjectstringOptional

The subject line of the email

Example: My Gift Voucher

Responses

201

Successful response

application/json

400

Bad Request: If the required parameters are missing or invalid.

401

Unauthorized: The user is not authorized to perform this action.

403

Forbidden: The user does not have permission to perform this action.

500

Internal server error.

post

HTTPcURLJavaScriptPython

POST /vouchers HTTP/1.1
Host: 
Authorization: Basic username:password
X-DotApparel-Name: text
shop: text
Content-Type: application/json
Accept: */*
Content-Length: 465

{
  "billingAddress": {
    "contactName": "DotApparel",
    "addressLine1": "Level 5",
    "addressLine2": "111 Cecil St",
    "city": "South Melbourne",
    "state": "VIC",
    "postcode": "3205",
    "country": "Australia"
  },
  "gateway": "shopify",
  "message": "Happy birthday!",
  "orderNumber": "#1001",
  "price": 100,
  "receiverEmail": "[e-mail]",
  "receiverName": "Smith James",
  "senderEmail": "[e-mail]",
  "senderMobile": "[phone]",
  "senderName": "John Williams",
  "subject": "My Gift Voucher"
}

{
  "data": {
    "id": 1,
    "orderNumber": "#1001",
    "personId": 73152,
    "warehouseId": 5441,
    "orderDateTime": "2023-03-02T14:31:42",
    "totalQuantity": "1",
    "totalTax": "10",
    "totalDiscount": "0",
    "totalDue": "100",
    "totalPayment": "100",
    "despatchType": "DespatchFromWarehouse",
    "addresses": {
      "billing": {
        "contactName": "DotApparel",
        "addressLine1": "Level 5",
        "addressLine2": "111 Cecil St",
        "city": "South Melbourne",
        "state": "VIC",
        "postcode": "3205",
        "country": "Australia"
      }
    },
    "contact": {
      "email": "[e-mail]",
      "phones": {
        "home": "[phone]",
        "mobile": "[phone]",
        "work": "[phone]"
      }
    },
    "orderDetails": [
      {
        "id": "32916920",
        "productId": "38664",
        "colourId": "79943",
        "skuId": "292544",
        "productCode": "GIFT",
        "productName": "Gift Voucher",
        "quantity": "1",
        "price": "100",
        "value": "100",
        "taxPercent": 10,
        "senderName": "John Williams",
        "receiverName": "Smith James",
        "status": "Shipped"
      }
    ],
    "payments": [
      {
        "id": 1441870,
        "origin": "CreditCard",
        "cardType": "VISA",
        "stan": 405555,
        "authCode": "512",
        "accountType": "Credit",
        "settlement": "20110625",
        "reference": "13525233_22255",
        "message": "Purchased on Monday",
        "merchantId": "Shopify",
        "amount": "100"
      }
    ],
    "pricesIncludeTax": true
  }
}

Retrieve Apparel21 gift voucher information or validate Apparel21 gift voucher

get

Scope: visitor and above

This endpoint retrieves information about Apparel21 gift voucher as well as validate the gift voucher.

The endpoint must accept a voucher number and a pin.

To validate a gift voucher, add 'amount' field as a query parameter.

The endpoint returns gift voucher information such as voucher number, expiry date, balance, used amount and validation id.

Authorizations

Path parameters

voucher_numberstringRequired

The Apparel21 voucher number

Query parameters

pinstringRequired

The Apparel21 voucher pin

amountstringOptional

To validate gift voucher - Amount of the voucher that will be used – this is only used for checking that “give change” vouchers will be used in full

"validationId" property will be included in the response

Header parameters

X-DotApparel-NamestringRequired

shopstringRequired

Responses

200

Successful response

application/json

400

Bad Request: Please enter a valid voucher number and pin

401

Unauthorized: The user is not authorized to perform this action.

403

Forbidden: The voucher does not exist Forbidden: The PIN is invalid

get

HTTPcURLJavaScriptPython

GET /vouchers/{voucher_number}?pin=text HTTP/1.1
Host: 
Authorization: Basic username:password
X-DotApparel-Name: text
shop: text
Accept: */*

{
  "data": {
    "voucherNumber": "4000105",
    "expiryDate": "2026-05-11T00:00:00",
    "originalAmmount": "50",
    "usedAmount": "0",
    "availableAmount": "50",
    "validationId": "a9e3accc-addf-4ca9-94bc-3cd499c50af0"
  }
}

Lock Apparel21 gift voucher

put

Scope: visitor and above

This endpoint is used to lock Apparel21 gift voucher.

The endpoint must accept a voucher number and a validation id.

Validation id is retrieved from the response after validating a gift voucher.

The endpoint returns a 200 status code if successful.

Authorizations

Path parameters

voucher_numberstringRequired

The Apparel21 voucher number

Query parameters

validation_idstringRequired

The validation id retrieved after validating gift voucher

If invalid, obtain a new one by making a request to validate gift voucher

lock_secondsnumberOptional

Number of seconds that voucher is to be locked for (if not supplied, lock is applied for 3600 seconds = 1 hour).

To unlock voucher, post another lock request with lock seconds of zero.

Header parameters

X-DotApparel-NamestringRequired

shopstringRequired

Responses

200

Successful response

application/json

400

Bad request: Please enter a valid voucher number and validation id

403

Forbidden: Incorrect validation id

put

HTTPcURLJavaScriptPython

PUT /vouchers/{voucher_number}?validation_id=text HTTP/1.1
Host: 
Authorization: Basic username:password
X-DotApparel-Name: text
shop: text
Accept: */*

{
  "data": {}
}