Coupon

The Coupon API is used to access, create, and modify the coupon objects on your business' account. The Coupon API is connected to the Invoice Items and Invoices and Quotes APIs, as coupons appear on both invoice items and invoices.

On this page





Coupon API Endpoints

These are the endpoints that are available under the /coupon path, which lists all the different coupons on the invoices on your business' account.

EndpointDescription
GET /coupon/current

Returns all coupon objects on an account in array format.

POST /coupon

Creates a new coupon object on an account.

Request body/payload: Must pass a coupon object in request body/payload. 

For these calls, you need to pass an array of coupon objects with all required fields and any fields you want to set filled in the body of the payload. We have an example of a coupon object in the responses section below and have indicated the required fields in the object values table at the bottom of this page.

PUT /coupon

Updates an existing coupon object.

Request body/payload: Must pass a coupon object in request body/payload.

For these calls, you need to pass a coupon object with all required fields and any fields you want to update filled in the body of the payload. We have an example of a coupon object in the responses section below and have indicated the required fields in the object values table at the bottom of this page.

DELETE /coupon/{couponId}Removes a coupon object from view by setting its active property to false.




Coupon API Parameters


Data points passed on in the request URL portion of the API call that are used to filter the data being requested. To aid with page load time, we have included pageNumber and pageSize parameters for server side pagination. The pageSize parameter will be the number of items shown per page.

ParameterTypeEndpoints to be used withDescription
pageNumberintegerGET /coupon/currentWorks with the pageSize parameter to determine how coupons get returned following the API call. The pageNumber value represents the number of pages on which the coupons that get returned appear.
pageSizeintegerGET /coupon/currentWorks with the pageNumber parameter to determine how coupons gets returned following the API call. The pageSize value represents the number of coupons appearing on each page that gets returned.




Coupon API Request Body/Payloads


The objects below represent the minimum viable objects to pass that are needed to create or update a coupon object. Check whether or not a property can be written to by looking at the Object Values table below to see if the property is writable.

POST /coupon
{
    "active": true,
    "amount": null,
    "businessId": 43111,
    "couponCode": "%1/2%",
    "couponName": "Half-price",
    "couponType": "DISCOUNT_PERCENT",
    "createdDate": 1681156011747,
    "createdUser": "JoeSchmo",
    "description": null,
    "endDate": "2023-05-05T04:00:00.000Z",
    "maxUseCount": 5,
    "modifiedDate": 1681156011747,
    "modifiedUser": "JoeSchmo",
    "percentage": 50,
    "reasonId": null,
    "reasonIdList": null
}
PUT /coupon
{
    "active": true,
    "amount": null,
    "businessId": 43111,
    "couponCode": "A1B2C3",
    "couponId": 68020,
    "couponName": "123",
    "couponType": "DISCOUNT_PERCENT",
    "createdDate": 1647889657148,
    "createdUser": "JoeSchmo",
    "currentUseCount": null,
    "description": null,
    "editing": true,
    "endDate": null,
    "maxUseCount": null,
    "modifiedDate": 1647889657148,
    "modifiedUser": "JoeSchmo",
    "noReasonsSelected": false,
    "percentage": 25,
    "reasonId": null,
    "reasonIdList": null
}




Coupon API Responses

GET /coupon
[{
    "active": true,
    "amount": null,
    "businessId": 43111,
    "couponCode": "001H223A445L667F889",
    "couponId": 11587,
    "couponName": "Half-off coupon",
    "couponType": "DISCOUNT_PERCENT",
    "createdDate": 1537548371992,
    "createdUser": "JoeSchmo",
    "currentUseCount": 2,
    "description": null,
    "endDate": null,
    "maxUseCount": null,
    "modifiedDate": 15357548406313,
    "modifiedUser": "JoeSchmo",
    "percentage": 50,
    "reasonId": null,
    "reasonIdList": null
}]
POST /coupon
[{
    "active": true,
    "amount": 5,
    "businessId": 43111,
    "couponCode": "00P00K987",
    "couponId": 11620,
    "couponName": "$5 off",
    "couponType": "DISCOUNT_AMOUNT",
    "createdDate": 15357551215927,
    "createdUser": "JoeSchmo",
    "currentUseCount": null,
    "description": null,
    "endDate": 1538107200000,
    "maxUseCount": 1,
    "modifiedDate": 15357551215927,
    "modifiedUser": "JoeSchmo",
    "percentage": null,
    "reasonId": null,
    "reasonIdList": [240127, 240094]
}]
PUT /coupon
{
    "active": true,
    "amount": null,
    "businessId": 43111,
    "couponCode": "00S55A47V94E38",
    "couponId": 11587,
    "couponName": "Quarter-off coupon",
    "couponType": "DISCOUNT_PERCENT",
    "createdDate": 1537548371992,
    "createdUser": "JoeSchmo",
    "currentUseCount": null,
    "description": null,
    "endDate": 1538107200000,
    "maxUseCount": null,
    "modifiedDate": 1537897140517,
    "modifiedUser": "JoeSchmo",
    "percentage": 25,
    "reasonId": null,
    "reasonIdList": null
}
DELETE /coupon/{couponId}
{
    "active": false,
    "amount": 10,
    "businessId": 43111,
    "couponCode": "%RV23",
    "couponId": 11950,
    "couponName": "$10 Cat Grooming",
    "couponType": "FIXED_AMOUNT",
    "createdDate": 1537970669701,
    "createdUser": "JoeSchmo",
    "currentUseCount": null,
    "description": null,
    "endDate": 1538107200000,
    "maxUseCount": 1,
    "modifiedDate": 1537970903423,
    "modifiedUser": "JoeSchmo",
    "percentage": null,
    "reasonId": null,
    "reasonIdList": [255109]
}




Coupon Object Values

Property NameTypeRequiredDescription
activebooleanYesIndicates whether or not the specified coupon should return on GET calls. 
amountinteger
Displays as monetary amount refunded by the specified coupon. Only filled on coupons of type DISCOUNT_AMOUNT.
businessIdintegerYesProvides unique numeric ID for the business to which the specified coupon belongs.
couponCodestringYesDisplays as code that is required to activate the specified coupon.
couponIdintegerYes, on PUT callsProvides unique numeric ID for the specified coupon.
couponNamestringYesDisplays as name given to the specified coupon. 
couponTypestringYesDisplays the coupon type for the specified coupon. Has acceptable values DISCOUNT_PERCENT, DISCOUNT_AMOUNT, FIXED_AMOUNT.
createdDateinteger
Displays as date the specified coupon was created in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. 
createdUserstring
Displays as username of the user who created the specified coupon.
currentUseCountinteger
Provides the number of times the specified coupon has been used.
descriptionstring
Displays as string that could be used to store info about the specified coupon. Not currently in use, but can be set to describe the specified coupon on the backend.
endDateinteger
Displays as date the specified coupon expires in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. 
maxUseCountinteger
Displays as number of redemptions allowed for the specified coupon. 
modifiedDateinteger
Displays as date the specified coupon was last modified in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. 
modifiedUserstring
Displays as username of the user who last modified the specified coupon.
percentageinteger
Displays as percentage of costs saved by the specified coupon. Only filled on coupons of type DISCOUNT_PERCENT.
reasonIdinteger
Displays as the reason ID of any services included in the specified coupon.
reasonIdListarray
Displays as reasonIds of services included in the specified coupon.