Coupon Service
===============

The coupon service provides endpoints for ensuring coupon code validity and recording/voiding coupon usage.

.. contents:: Topics

Request Objects
~~~~~~~~~~~~~~~

.. http:jsonentity:: CouponRedemptionInfo

   This object represents the packet of information to be recorded about the coupon usage. If the check number is not provided, then the coupon usage
   cannot be voided

   :jsonparam  Int    merchantId:         *(required)* Paytronix-assigned merchant ID to perform the operation in.
   :jsonparam  Int    couponId:           *(required)* Coupon ID as returned by validateCouponUsage
   :jsonparam  String storeCode:          *(required)* Store Code of store at which coupon is being redeemed
   :jsonparam  String redemptionDatetime: *(required)* The time at which the coupon was redeemed. Valid format is "yyyy-MM-ddTHH:mm:ss".
   :jsonparam  String checkOpenDatetime:  *(required)* The time at which the coupon was opened. Valid format is "yyyy-MM-ddTHH:mm:ss".
   :jsonparam  Int    operatorId:         *(optional)* Optionally specify the operator of the register
   :jsonparam  String terminalId:         *(optional)* Optionally specify the register
   :jsonparam  String checkNumber:        *(optional)* Optionally specify the check number (NOTE: for voidCouponUsage, a checkNumber is required)
   :jsonparam  Int    integrationId:      *(optional)* Optionally specify the integration
   :jsonparam  String printedCardNumber:  *(optional)* Optionally specify a card number, if a check was associated with a loyalty customer

Endpoints
---------

Validate Coupon Usage
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. http:get:: coupon/validateCouponUsage.json

   Attempts to find a currently-valid coupon based on the coupon code and merchant Id. The coupon must be configured in the PXS, and will have an associated Redeem Wallet
   which will determine the "reward" the coupon is valid for. If it finds a coupon, it will return this redeem wallet.
   Should be called by the entity processing the check before the check has been paid for.
   
   The following authentication methods are allowed for this endpoint:

   * :ref:`b2b_auth`

   :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in.
   :query String couponCode: *(required)*  The Coupon Code associated with the coupon, as configured in the PXS.

.. http:response:: success

   :jsonparam String result: *(required)*  ``success``
   :jsonparam Int couponId: *(required)* A unique integer that identifies the coupon found. Use this for reportCouponUsage
   :jsonparam Int walletCode: *(required)* The wallet code of the redeem wallet associated with the coupon
.. http:response:: failure

   :jsonparam String result: *(required)*  ``failure``
   :jsonparam String errorCode: *(required)* The error code validate_coupon.no_coupon indicates that no coupon was found. Other error codes will be given as a result of a configuration error or unexpected behavior
   :jsonparam String errorMessage: *(required)* Further explanation of the error code


Report Coupon Usage
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. http:put:: coupon/reportCouponUsage.json

   Records information about a coupon after it was applied to a given check, for reporting purposes. 
   Should be called after a coupon has been applied to a check, on the condition that its reward was in fact used.
   
   The following authentication methods are allowed for this endpoint:

   * :ref:`b2b_auth`

   :jsonparam Object couponRedemptionInfo: *(required)* Information to record. See :http:jsonentity:`CouponRedemptionInfo` for details.

.. http:response:: success

   :jsonparam String result: *(required)*  ``success`` No further action necessary
.. http:response:: failure

   :jsonparam String result: *(required)*  ``failure``
   :jsonparam String errorCode: *(required)* The error code of the failure.
   :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure.

Void Coupon Usage
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. http:post:: coupon/voidCouponUsage.json

   Voids a particular coupon usage, removing it from reporting. Identifies a specific usage by check number, store code, and redemption date, so the check number must be specified in the corresponding call
   to reportCouponUsage. 
   
   The following authentication methods are allowed for this endpoint:

   * :ref:`b2b_auth`

   :jsonparam Integer merchantId:    *(required)* Paytronix-assigned merchant ID to perform the operation in.
   :jsonparam String checkNumber:    *(required)* Check number associated with the coupon usage in reportCouponUsage call
   :jsonparam String storeCode:      *(required)* Store Code at which the coupon was used
   :jsonparam String redemptionDate: *(required)* Date at which the coupon was used

.. http:response:: success

   :jsonparam String result: *(required)*  ``success`` No further action necessary
.. http:response:: failure

   :jsonparam String result: *(required)*  ``failure``
   :jsonparam String errorCode: *(required)* The error code of the failure.
   :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure.