saveIssuedCoupon

Register a printed coupon that has been issued to a customer, or update information on an existing coupon.

Issued coupon must have a unique identifier. Since coupons may carry monetary value, Erply keeps track of issued coupons and allows to validate (verify) a coupon when customer comes to redeem it.

The recommended workflow is as follows:

  1. Register a printed coupon with saveIssuedCoupon.
  2. When customer returs to the store to redeem the coupon, use API verifyIssuedCoupon to check that the coupon is valid (ie. the coupon exists in the system, has not been redeemed yet, and has not expired).
  3. Call redeemIssuedCoupon to redeem the coupon, so that it could not be used twice.

To retrieve coupons, use API call getIssuedCoupons.

saveIssuedCoupon also allows you to update the attributes of an existing coupon. DO NOT use it for marking a coupon as redeemed — there is a separate call, redeemIssuedCoupon, that you should use for that. Only use saveIssuedCoupon if you want to update coupon's expiry date or edit how it was purchased or who redeemed it (customer name, store, employee, etc.)

A coupon may have a "printing cost" — if the coupon is issued, a certain amount of reward points is subtracted from customer's point balance. This is done automatically by the API. However, if customer does not have a sufficient amount of points, the coupon does not get issued and API returns error 1042 instead.

Input parameters

Parameter name Description Possible value Required
issuedCouponID Issued coupon ID.
Set this parameter to update an existing issued coupon.		 integer
couponID ID of the coupon code (see getCoupons). Coupon code is like the "blueprint" or "type" of a printed coupon. The "blueprint" specifies in what circumstances the coupons will be printed from POS, and what promotion will apply when customer returns with the coupon — ie., what discount or extra value it effectively carries.

Not required when updating an existing coupon.		 integer yes
uniqueIdentifier A unique identifier for this printed coupon. You may leave this parameter unset and have API generate an identifier automatically. However, if you need, you may assign it yourself. For reference, here is a specification how Erply's Offline POS generates coupon IDs:

An identifier consists of digits only, and is structured as follows:
  1. Point of sale ID - max 3 digits (left padding not needed)
  2. Coupon ID - 4 digits (padded with zeroes)
  3. Sequential number (each register may keep its own sequence) - 7 digits (padded with zeroes)
  4. 4 random digits - to ensure within reason that malicious customer would not be able to guess the identifiers of outstanding coupons, and fabricate coupons using guessed identifiers

Note that if this parameter is not unique, error code 1012 is returned.

When creating a new coupon, either uniqueIdentifier or pointOfSaleID is required; if you do not set the former, then the latter is compulsory.

When updating an existing coupon, this field is not required. But it is possible to update an existing coupon and change its uniqueIdentifier, if you need that.		 String (20) yes
invoiceID Invoice the coupon was issued with.

If you want to save an invoice and an associated coupon together in one bulk request, set this field to a special value: "CURRENT_INVOICE_ID". Normally, creating two records where one references the other cannot be done within one bulk request; you would have to retrieve one record's ID before you can create the other. This is a special workaround for savePayment, saveGiftCard, saveIssuedCoupon, redeemIssuedCoupon, and subtractCustomerRewardPoints.

Note that if saving the invoice results in an error, the payments, coupons etc. will be created and coupons redeemed nevertheless, but without a reference to any invoice. For better error checking you may still want to do saveSalesDocument as a separate request.

Alias: issuedInvoiceID.		 integer
customerID Customer the coupon was issued to.

Alias: issuedCustomerID.		 integer
warehouseID Store or location where the coupon was issued.

Alias: issuedWarehouseID.		 integer
pointOfSaleID Register where the coupon was issued.

Either uniqueIdentifier or pointOfSaleID is required; if you do not set the former, then the latter is compulsory.

Alias: issuedPointOfSaleID.		 integer yes
employeeID Salesperson who issued the coupon.

Alias: issuedEmployeeID.		 integer
timestamp Issue time.

Alias: issuedTimestamp.		 integer Unix timestamp. yes
expiryDate Expiry date ISO date (yyyy-mm-dd)
isPrintedAutomatically Denotes whether the coupon was printed automatically (as per coupon terms and conditions) or did the salesperson choose it manually. Values other than 0 are interpreted as "true". Integer (1 or 0)
doNotSubtractRewardPoints If set to 1, API will not subtract reward points from customer's point balance. Integer (1 or 0)
redeemedInvoiceID Invoice the coupon was redeemed with.

DO NOT use the saveIssuedCoupon API call, nor any of the following fields, to mark a coupon as redeemed. There is a separate API call, redeemIssuedCoupon, for that. Only use these fields if the coupon has already been redeemed and you want to edit coupon data without changing its status.

When creating a new coupon, these fields do not (currently) have any effect.		 integer
redeemedCustomerID integer
redeemedTimestamp Integer (Unix timestamp)
redeemedWarehouseID integer
redeemedPointOfSaleID integer
redeemedEmployeeID integer

Response

Field name Type Description
issuedCouponID integer Returns ID of the created or updated item.
couponID integer ID of the coupon code.
couponCode string
couponName string
couponDescription string
uniqueIdentifier String (20) Returns unique identifier of the coupon.
printingCostInRewardPoints integer Printing cost in reward points. This is an informative field; you do not need to do anything with that value. These points are automatically subtracted from customer's point balance by the API. If the customer does not have enough points, error 1042 is returned.