Referral Coupon Management

Retrieving customer's referral coupon

get

Retrieves the referral coupon of a given customer in the database.

When the existing customer shares the referral code with a potential customer, the referred customer can benefit from the discount in a form of a fixed monetary amount.

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

Path parameters

customerNumberstringRequired

Customer number (ID) of customer.

tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Responses

200

The referral coupon has been successfully retrieved.

application/json

Coupons describe voucher alike commerce capabilities.

codestringOptional

e.g.: WINTER-SALE, 10OFF (read-only)

namestringRequired

Coupon name.

descriptionstringOptional

Coupon description.

discountTypestring · enumRequired

PERCENT for relative values, ABSOLUTE for float values, referring to a specific currency, FREE_SHIPPING for reducing the shipping cost to 0.

Possible values:

discountPercentagenumber · max: 100Optional

A discount percentage within the range [0.00, 100.00]. Must be specified only if type is PERCENT.

allowAnonymousbooleanOptional

Specifies if the coupon can be redeemed by anonymous users.

Default: false

maxRedemptionsnumberOptional

Maximum number of redemptions; -1 designates 'unlimited' (seller-only).

Default: -1

maxRedemptionsPerCustomernumberOptional

Maximum number of redemptions per customer; -1 designates 'unlimited'. Cannot be specified for coupons which can be redeemed by anonymous users.

Default: -1

issuedTostringRequired

The Id of the customer who originally received the coupon (seller-only).

referralCouponbooleanOptional

Indicates if the coupon is type of referral coupon. This property is read only.

redemptionCountnumberOptional

The number of times a specific coupon has been redeemed. Read-only, set through server (seller-only).

statusstring · enumRequired

Current status of the coupon (read-only). INACTIVE: the coupon is only valid in the future; VALID: can be used; EXPIRED: the coupon validity period has expired; USED: the maximum number of redemptions for the coupon has been reached.

Possible values:

deletedbooleanOptional

Flag to mark a coupon as deleted (a.k.a. Soft delete). It is a read-only and seller-only attribute

204

No content if there is no referral coupon

400

Request syntactically incorrect. Details of the error are included in the response payload.

application/json

401

Example response

application/json

404

The requested resource does not exist.

application/json

500

Some server side error occurred.

application/json

get

/coupon/{tenant}/referral-coupons/{customerNumber}

HTTPcURLJavaScriptPython

GET /coupon/{tenant}/referral-coupons/{customerNumber} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "allowAnonymous": true,
  "code": "REF_30",
  "deleted": false,
  "description": "A referral Coupon",
  "discountAbsolute": {
    "amount": 8,
    "currency": "USD"
  },
  "discountType": "ABSOLUTE",
  "issuedTo": "61443563",
  "referralCoupon": true,
  "maxRedemptions": -1,
  "maxRedemptionsPerCustomer": -1,
  "name": "Empfehlungsgutschein John Doe (Emporix)",
  "redemptionCount": 0,
  "restrictions": {
    "validFor": []
  },
  "status": "VALID"
}

Creating a referral coupon code for a given customer

post

Creates a referral coupon code for a specific customer in the database. If the coupon code exists, returns it without creating a new coupon.

Note: There can only be one referral coupon generated per customer.

When the existing customer shares the referral code with a potential customer, the referred customer can benefit from the discount in a form of a fixed monetary amount.

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

Path parameters

customerNumberstringRequired

Customer number (ID) of customer.

tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Responses

200

The referral coupon code has been successfully retrieved.

application/json

Coupons describe voucher alike commerce capabilities.

codestringOptional

e.g.: WINTER-SALE, 10OFF (read-only)

namestringRequired

Coupon name.

descriptionstringOptional

Coupon description.

discountTypestring · enumRequired

PERCENT for relative values, ABSOLUTE for float values, referring to a specific currency, FREE_SHIPPING for reducing the shipping cost to 0.

Possible values:

discountPercentagenumber · max: 100Optional

A discount percentage within the range [0.00, 100.00]. Must be specified only if type is PERCENT.

allowAnonymousbooleanOptional

Specifies if the coupon can be redeemed by anonymous users.

Default: false

maxRedemptionsnumberOptional

Maximum number of redemptions; -1 designates 'unlimited' (seller-only).

Default: -1

maxRedemptionsPerCustomernumberOptional

Maximum number of redemptions per customer; -1 designates 'unlimited'. Cannot be specified for coupons which can be redeemed by anonymous users.

Default: -1

issuedTostringRequired

The Id of the customer who originally received the coupon (seller-only).

referralCouponbooleanOptional

Indicates if the coupon is type of referral coupon. This property is read only.

redemptionCountnumberOptional

The number of times a specific coupon has been redeemed. Read-only, set through server (seller-only).

statusstring · enumRequired

Current status of the coupon (read-only). INACTIVE: the coupon is only valid in the future; VALID: can be used; EXPIRED: the coupon validity period has expired; USED: the maximum number of redemptions for the coupon has been reached.

Possible values:

deletedbooleanOptional

Flag to mark a coupon as deleted (a.k.a. Soft delete). It is a read-only and seller-only attribute

400

Request syntactically incorrect. Details of the error are included in the response payload.

application/json

401

Example response

application/json

404

The requested resource does not exist.

application/json

500

Some server side error occurred.

application/json

post

/coupon/{tenant}/referral-coupons/{customerNumber}

HTTPcURLJavaScriptPython

POST /coupon/{tenant}/referral-coupons/{customerNumber} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "allowAnonymous": true,
  "code": "REF_30",
  "deleted": false,
  "description": "A referral Coupon",
  "discountAbsolute": {
    "amount": 8,
    "currency": "USD"
  },
  "discountType": "ABSOLUTE",
  "issuedTo": "61443563",
  "referralCoupon": true,
  "maxRedemptions": -1,
  "maxRedemptionsPerCustomer": -1,
  "name": "Empfehlungsgutschein John Doe (Emporix)",
  "redemptionCount": 0,
  "restrictions": {
    "validFor": []
  },
  "status": "VALID"
}