coupon
/coupon
/coupon
Retrieves coupons for this account. If no parameters are specified, all coupons will be returned. You will need to make multiple API calls in order to retrieve the entire result set since this API performs result set pagination.
| Parameter | Description | Location | Data Type | Required |
|---|---|---|---|---|
| merchant_code | Merchant code | query | string | optional |
| description | Description | query | string | optional |
| coupon_type | Coupon type | query | string | optional |
| start_date_begin | Start date begin | query | string | optional |
| start_date_end | Start date end | query | string | optional |
| expiration_date_begin | Expiration date begin | query | string | optional |
| expiration_date_end | Expiration date end | query | string | optional |
| affiliate_oid | Affiliate oid | query | integer (int32) | optional |
| exclude_expired | Exclude expired | query | boolean | optional |
| _limit | The maximum number of records to return on this one API call. (Max 200)
Default: 100 |
query | integer | optional |
| _offset | Pagination of the record set. Offset is a zero based index.
Default: 0 |
query | integer | optional |
| _sort | The sort order of the coupons. See Sorting documentation for examples of using multiple values and sorting by ascending and descending.
Allowed Values
|
query | string | optional |
| _expand | The object expansion to perform on the result. See documentation for examples | query | string | optional |
Insert a coupon on the UltraCart account.
| Parameter | Description | Location | Data Type | Required |
|---|---|---|---|---|
| coupon | Coupon to insert | body | Coupon | required |
| _expand | The object expansion to perform on the result. See documentation for examples | query | string | optional |
Retrieves a single coupon using the specified merchant code.
| Parameter | Description | Location | Data Type | Required |
|---|---|---|---|---|
| merchant_code | The coupon merchant code to retrieve. | path | string | required |
| _expand | The object expansion to perform on the result. See documentation for examples | query | string | optional |
Generate one time codes by merchant code
| Parameter | Description | Location | Data Type | Required |
|---|---|---|---|---|
| merchant_code | The merchant code to generate one time codes. | path | string | required |
| coupon_codes_request | Coupon code generation parameters | body | CouponCodesRequest | required |
Retrieves coupons from the account. If no parameters are specified, all coupons will be returned. You will need to make multiple API calls in order to retrieve the entire result set since this API performs result set pagination.
| Parameter | Description | Location | Data Type | Required |
|---|---|---|---|---|
| coupon_query | Coupon query | body | CouponQuery | required |
| _limit | The maximum number of records to return on this one API call. (Max 200)
Default: 100 |
query | integer | optional |
| _offset | Pagination of the record set. Offset is a zero based index.
Default: 0 |
query | integer | optional |
| _sort | The sort order of the coupons. See Sorting documentation for examples of using multiple values and sorting by ascending and descending.
Allowed Values
|
query | string | optional |
| _expand | The object expansion to perform on the result. See documentation for examples | query | string | optional |
Delete a coupon on the UltraCart account.
| Parameter | Description | Location | Data Type | Required |
|---|---|---|---|---|
| coupon_oid | The coupon_oid to delete. | path | integer (int32) | required |
Retrieves a single coupon using the specified coupon profile oid.
| Parameter | Description | Location | Data Type | Required |
|---|---|---|---|---|
| coupon_oid | The coupon oid to retrieve. | path | integer (int32) | required |
| _expand | The object expansion to perform on the result. See documentation for examples | query | string | optional |
Update a coupon on the UltraCart account.
| Parameter | Description | Location | Data Type | Required |
|---|---|---|---|---|
| coupon | Coupon to update | body | Coupon | required |
| coupon_oid | The coupon_oid to update. | path | integer (int32) | required |
| _expand | The object expansion to perform on the result. See documentation for examples | query | string | optional |
Generate one time codes for a coupon
| Parameter | Description | Location | Data Type | Required |
|---|---|---|---|---|
| coupon_oid | The coupon oid to generate codes. | path | integer (int32) | required |
| coupon_codes_request | Coupon code generation parameters | body | CouponCodesRequest | required |
| Name | Data Type | Description |
|---|---|---|
| affiliate_oid | integer (int32) | Associates an order with an affiliate when this value is set. |
| allow_multiple_one_time_codes | boolean | True if multiple one time codes for this coupon can be used on a cart at the same time. |
| amount_off_items | CouponAmountOffItems | Amount off items |
| amount_off_shipping | CouponAmountOffShipping | Amount off shipping |
| amount_off_shipping_with_items_purchase | CouponAmountOffShippingWithItemsPurchase | Amount off shipping with items purchase |
| amount_off_subtotal | CouponAmountOffSubtotal | Amount off subtotal |
| amount_off_subtotal_and_free_shipping | CouponAmountOffSubtotalFreeShippingWithPurchase | Amount off subtotal and free shipping with purchase |
| amount_off_subtotal_and_shipping | CouponAmountOffSubtotalAndShipping | Amount off subtotal and shipping |
| amount_off_subtotal_with_block_purchase | CouponAmountOffSubtotalWithBlockPurchase | Amount off subtotal with block purchase |
| amount_off_subtotal_with_items_purchase | CouponAmountOffSubtotalWithItemsPurchase | Amount off subtotal with items purchase |
| automatically_apply_coupon_codes | CouponAutomaticallyApplyCouponCodes | Additional coupon codes to automatically apply |
| calculated_description | (read only) string | Calculated description displayed to the customer if no description is specified. |
| can_be_used_with_other_coupons | boolean | True if this coupon can be used with other coupons in a single order. |
| coupon_oid | integer (int32) | Coupon oid. |
| coupon_type | string(65) | Coupon type. |
| description | string(50) | Description of the coupon up to 50 characters. |
| discount_item_with_item_purchase | CouponDiscountItemWithItemPurchase | Discount item with item purchase |
| discount_items | CouponDiscountItems | Discount items |
| expiration_dts | string (dateTime) | Date/time when coupon expires |
| free_item_and_shipping_with_subtotal | CouponFreeItemAndShippingWithSubtotal | Free items and shipping with subtotal |
| free_item_with_item_purchase | CouponFreeItemWithItemPurchase | Free item with item purchase |
| free_item_with_subtotal | CouponFreeItemWithSubtotal | Free items with subtotal |
| free_items_with_item_purchase | CouponFreeItemsWithItemPurchase | Free items with item purchase |
| free_items_with_mixmatch_purchase | CouponFreeItemsWithMixMatchPurchase | Free items with Mix and Match purchase |
| free_shipping | CouponFreeShipping | Free shipping |
| free_shipping_specific_items | CouponFreeShippingSpecificItems | Free shipping specific items |
| free_shipping_with_items_purchase | CouponFreeShippingWithItemsPurchase | Free shipping with items purchase |
| free_shipping_with_subtotal | CouponFreeShippingWithSubtotal | Free shipping with subtotal |
| merchant_code | string(20) | Merchant code of coupon up to 20 characters. |
| merchant_notes | string(250) | Internal notes about this coupon. These are not visible to customer. |
| multiple_amounts_off_items | CouponMultipleAmountsOffItems | Multiple amounts off items |
| no_discount | CouponNoDiscount | No discount |
| percent_off_item_with_items_quantity_purchase | CouponPercentOffItemWithItemsQuantityPurchase | Percent off item with items quantity purchase |
| percent_off_items | CouponPercentOffItems | Percent off items |
| percent_off_items_and_free_shipping | CouponPercentOffItemsAndFreeShipping | Percent off items and free shipping |
| percent_off_items_with_items_purchase | CouponPercentOffItemsWithItemsPurchase | Percent off items with items purchase |
| percent_off_retail_price_items | CouponPercentOffRetailPriceItems | Percent off retail price items |
| percent_off_shipping | CouponPercentOffShipping | Percent off shipping |
| percent_off_subtotal | CouponPercentOffSubtotal | Percent off subtotal |
| percent_off_subtotal_and_free_shipping | CouponPercentOffSubtotalAndFreeShipping | Percent off subtotal and free shipping |
| percent_off_subtotal_limit | CouponPercentOffSubtotalLimit | Percent off subtotal with limit |
| percent_off_subtotal_with_items_purchase | CouponPercentOffSubtotalWithItemsPurchase | Percent off subtotal with items purchase |
| percent_off_subtotal_with_subtotal | CouponPercentOffSubtotalWithSubtotal | Percent off subtotal with subtotal |
| quickbooks_code | string(20) | Quickbooks accounting code. |
| restrict_by_postal_codes | array of string | Optional list of postal codes which restrict a coupon to within these postal codes. |
| restrict_by_screen_branding_theme_codes | array of CouponRestriction | Optional list of legacy screen branding theme codes to limit coupon use to only those themes. |
| restrict_by_storefronts | array of CouponRestriction | Optional list of storefronts to limit coupon use to only those storefronts. |
| start_dts | string (dateTime) | Date/time when coupon is valid |
| tiered_amount_off_item | CouponTieredAmountOffItem | Tiered amount off item |
| tiered_amount_off_subtotal | CouponTieredAmountOffSubtotal | Tiered amount off subtotal |
| tiered_percent_off_items | CouponTieredPercentOffItems | Tiered percent off items |
| tiered_percent_off_shipping | CouponTieredPercentOffShipping | Tiered percent off shipping |
| tiered_percent_off_subtotal | CouponTieredPercentOffSubtotal | Tiered percent off subtotal |
| usable_by | string(50) | Who may use this coupon. |
| Name | Data Type | Description |
|---|---|---|
| currency_code | string(3) | The ISO-4217 three letter currency code the customer is viewing prices in |
| discount_amount | number | The amount of shipping discount |
| items | array of string | A list of items which are eligible for the discount amount. |
| Name | Data Type | Description |
|---|---|---|
| currency_code | string(3) | The ISO-4217 three letter currency code the customer is viewing prices in |
| discount_amount | number | The amount of subtotal discount |
| shipping_methods | array of string | One or more shipping methods that may be used with this coupon |
| Name | Data Type | Description |
|---|---|---|
| currency_code | string(3) | The ISO-4217 three letter currency code the customer is viewing prices in |
| discount_amount | number | The amount of shipping discount |
| items | array of string | A list of items of which at least one must be purchased for coupon to be valid. |
| shipping_methods | array of string | One or more shipping methods that may receive this discount |
| Name | Data Type | Description |
|---|---|---|
| currency_code | string(3) | The ISO-4217 three letter currency code the customer is viewing prices in |
| discount_amount | number | The amount of subtotal discount |
| Name | Data Type | Description |
|---|---|---|
| currency_code | string(3) | The ISO-4217 three letter currency code the customer is viewing prices in |
| discount_amount | number | The amount of subtotal discount |
| Name | Data Type | Description |
|---|---|---|
| currency_code | string(3) | The ISO-4217 three letter currency code the customer is viewing prices in |
| discount_amount | number | The amount of subtotal discount |
| purchase_amount | number | The purchase amount to qualify for subtotal discount and free shipping |
| shipping_methods | array of string | One or more shipping methods that may be free |
| Name | Data Type | Description |
|---|---|---|
| currency_code | string(3) | The ISO-4217 three letter currency code the customer is viewing prices in |
| discount_amount | number | The amount of subtotal discount |
| required_purchase_item | string | Required item that must be purchased for coupon to be valid |
| required_purchase_quantity | integer (int32) | Discount amount is multiplied by the number of blocks. A block is this many quantity of the required item. |
| Name | Data Type | Description |
|---|---|---|
| currency_code | string(3) | The ISO-4217 three letter currency code the customer is viewing prices in |
| discount_amount | number | The amount of shipping discount |
| items | array of string | A list of items of which a quantity of one or many must be purchased for coupon to be valid. |
| required_purchase_quantity | integer (int32) | The quantity of items that must be purchased for the discount to be applied. |
| Name | Data Type | Description |
|---|---|---|
| coupon_codes | array of string | The coupon codes to automatically apply if this coupon is applied |
| Name | Data Type | Description |
|---|---|---|
| error | Error | Error object if unsuccessful |
| expiration_dts | string | Expiration Date |
| expiration_seconds | integer (int32) | Expiration seconds |
| metadata | ResponseMetadata | Meta-data about the response such as payload or paging information |
| quantity | integer (int32) | Quantity |
| success | boolean | Indicates if API call was successful |
| Name | Data Type | Description |
|---|---|---|
| coupon_codes | array of string | Coupon codes |
| error | Error | Error object if unsuccessful |
| expiration_dts | string (dateTime) | Expiration date |
| metadata | ResponseMetadata | Meta-data about the response such as payload or paging information |
| success | boolean | Indicates if API call was successful |
| Name | Data Type | Description |
|---|---|---|
| currency_code | string(3) | The ISO-4217 three letter currency code the customer is viewing prices in |
| discount_price | number | The price (unit cost) of the discounted item |
| items | array of string | A list of items that are eligible for this discount_price. |
| limit | integer (int32) | The (optional) maximum quantity of discounted items. |
| Name | Data Type | Description |
|---|---|---|
| currency_code | string(3) | The ISO-4217 three letter currency code the customer is viewing prices in |
| discount_item | string | The item that will be sold at the discount_price when required_purchase_item is purchased. |
| discount_price | number | The price (unit cost) of the discounted item |
| limit | integer (int32) | The (optional) maximum quantity of discounted items. |
| required_purchase_item | string | The item that must be purchased for the discount to be applied to the discount item. |
| Name | Data Type | Description |
|---|---|---|
| coupon_types | (read only) array of string | coupon_types |
| Name | Data Type | Description |
|---|---|---|
| currency_code | string(3) | The ISO-4217 three letter currency code the customer is viewing prices in |
| items | array of string | A list of items that are eligible for this discount_price. |
| limit | integer (int32) | The limit of free items that may be received when purchasing multiple items |
| shipping_methods | array of string | One or more shipping methods that may be free |
| subtotal_amount | number | The amount of subtotal required to receive the discount percent |
| Name | Data Type | Description |
|---|---|---|
| free_item | string | The item id of the free item that will be received when the required mix and match group quantity is purchased. |
| free_quantity | integer (int32) | The quantity of free item that will be received. |
| limit | integer (int32) | The limit of free items that may be received when purchasing multiple items |
| required_purchase_item | string | Required item that must be purchased for coupon to be valid |
| required_purchase_quantity | integer (int32) | Required quantity of mix and match group items that must be purchased for coupon to be valid |
| Name | Data Type | Description |
|---|---|---|
| free_item | string | The item id of the free item that will be received when the required mix and match group quantity is purchased. |
| free_quantity | integer (int32) | The quantity of free item that will be received. |
| limit | integer (int32) | The limit of free items that may be received when purchasing multiple mix and match group items |
| required_purchase_mix_and_match_group | string | Required mix and match group that must be purchased for coupon to be valid |
| required_purchase_quantity | integer (int32) | Required quantity of mix and match group items that must be purchased for coupon to be valid |
| Name | Data Type | Description |
|---|---|---|
| items | array of string | A list of free items which will receive a discount if one of the required purchase items is purchased. |
| limit | integer (int32) | The (optional) maximum quantity of discounted items. |
| required_purchase_items | array of string | Required items (at least one from the list) that must be purchased for coupon to be valid |
| Name | Data Type | Description |
|---|---|---|
| currency_code | string(3) | The ISO-4217 three letter currency code the customer is viewing prices in |
| items | array of string | A list of items that are eligible for this discount_price. |
| limit | integer (int32) | The limit of free items that may be received when purchasing multiple items |
| subtotal_amount | number | The amount of subtotal required to receive the discount percent |
| Name | Data Type | Description |
|---|---|---|
| shipping_methods | array of string | One or more shipping methods that may be used with this coupon |
| Name | Data Type | Description |
|---|---|---|
| items | array of string | A list of items of which at least one must be purchased for coupon to be valid. |
| Name | Data Type | Description |
|---|---|---|
| items | array of string | A list of items of which at least one must be purchased for coupon to be valid. |
| shipping_methods | array of string | One or more shipping methods that may receive this discount |
| Name | Data Type | Description |
|---|---|---|
| currency_code | string(3) | The ISO-4217 three letter currency code the customer is viewing prices in |
| purchase_amount | number | The purchase amount to qualify for subtotal discount and free shipping |
| shipping_methods | array of string | One or more shipping methods that may be used with this coupon |
| Name | Data Type | Description |
|---|---|---|
| discounts | array of CouponTierItemDiscount | A list of item discounts. |
| limit | integer (int32) | The (optional) maximum quantity of items that may receive a discount. |
| Name | Data Type | Description |
|---|
| Name | Data Type | Description |
|---|---|---|
| discount_percent | number | The percentage of subtotal discount |
| excluded_items | array of string | A list of items which cannot be discounted. |
| items | array of string | An optional list of items which will receive a discount. If blank, discount applies to all items except excluded items. |
| limit | integer (int32) | The (optional) maximum quantity of discounted items. |
| Name | Data Type | Description |
|---|---|---|
| discount_percent | number | The percentage of subtotal discount |
| excluded_items | array of string | A list of items which cannot be discounted. |
| items | array of string | An optional list of items which will receive a discount. If blank, discount applies to all items except excluded items. |
| Name | Data Type | Description |
|---|---|---|
| discount_percent | number | The percentage of subtotal discount |
| items | array of string | A list of items which will receive a discount if one of the required purchase items is purchased. |
| limit | integer (int32) | The (optional) maximum quantity of discounted items. |
| required_purchase_items | array of string | Required items (at least one from the list) that must be purchased for coupon to be valid |
| Name | Data Type | Description |
|---|---|---|
| discount_percent | number | The percentage of subtotal discount |
| items | array of string | A list of items which will receive a discount if one of the required purchase items is purchased. |
| limit | integer (int32) | The (optional) maximum quantity of discounted items. |
| required_purchase_items | array of string | Required items (at least one from the list) that must be purchased for coupon to be valid |
| required_purchase_quantity | integer (int32) | The quantity of items that must be purchased for the discount to be applied. |
| Name | Data Type | Description |
|---|---|---|
| discount_percent | number | The percentage of subtotal discount |
| excluded_items | array of string | A list of items which cannot be discounted. |
| items | array of string | An optional list of items which will receive a discount. If blank, discount applies to all items except excluded items. |
| limit | integer (int32) | The (optional) maximum quantity of discounted items. |
| Name | Data Type | Description |
|---|---|---|
| discount_percent | number | The percentage of subtotal discount |
| shipping_methods | array of string | One or more shipping methods that may be used with this coupon |
| Name | Data Type | Description |
|---|---|---|
| discount_percent | number | The percentage of subtotal discount |
| Name | Data Type | Description |
|---|---|---|
| discount_percent | number | The percentage of subtotal discount |
| shipping_methods | array of string | One or more shipping methods that may be free |
| Name | Data Type | Description |
|---|---|---|
| currency_code | string(3) | The ISO-4217 three letter currency code the customer is viewing prices in |
| discount_percent | number | The percentage of subtotal discount |
| limit | number | The maximum amount of subtotal used to determine discount. |
| Name | Data Type | Description |
|---|---|---|
| discount_percent | number | The percentage of subtotal discount |
| items | array of string | A list of items of which at least one must be purchased for coupon to be valid. |
| Name | Data Type | Description |
|---|---|---|
| currency_code | string(3) | The ISO-4217 three letter currency code the customer is viewing prices in |
| discount_percent | number | The percentage of subtotal discount |
| subtotal_amount | number | The amount of subtotal required to receive the discount percent |
| Name | Data Type | Description |
|---|---|---|
| affiliate_oid | integer (int32) | Affiliate oid |
| coupon_type | string | The type of coupon. |
| description | string | Description of this coupon |
| exclude_expired | boolean | Exclude expired coupons if true |
| expiration_dts_begin | string (dateTime) | Expiration date begin |
| expiration_dts_end | string (dateTime) | Expiration date begin |
| merchant_code | string | Merchant code is a unique character string for this coupon. |
| start_dts_begin | string (dateTime) | Start date begin |
| start_dts_end | string (dateTime) | Start date end |
| Name | Data Type | Description |
|---|---|---|
| coupon | Coupon | Coupon |
| error | Error | Error object if unsuccessful |
| metadata | ResponseMetadata | Meta-data about the response such as payload or paging information |
| success | boolean | Indicates if API call was successful |
| Name | Data Type | Description |
|---|---|---|
| invalidForThis | boolean | |
| name | string | |
| validForThis | boolean | |
| validOnlyForThis | boolean |
| Name | Data Type | Description |
|---|---|---|
| coupons | array of Coupon | |
| error | Error | Error object if unsuccessful |
| metadata | ResponseMetadata | Meta-data about the response such as payload or paging information |
| success | boolean | Indicates if API call was successful |
| Name | Data Type | Description |
|---|---|---|
| discount_amount | number | The amount of subtotal discount |
| subtotal_amount | number | The amount of subtotal required to receive the discount amount |
| Name | Data Type | Description |
|---|---|---|
| item | string | The item being discounted by this coupon. |
| limit | number | The maximum amount of total discount by this coupon. |
| tiers | array of CouponTierQuantityAmount | A list of discount tiers. |
| Name | Data Type | Description |
|---|---|---|
| items | array of string | An optional list of items of which a quantity of one or many must be purchased for coupon to be valid. If empty, all items apply toward subtotal amount. |
| tiers | array of CouponTierAmount | A list of discount tiers. |
| Name | Data Type | Description |
|---|---|---|
| items | array of string | A list of items of which at least one must be purchased for coupon to be valid. |
| limit | number | The maximum amount of total discount by this coupon. |
| tiers | array of CouponTierQuantityPercent | A list of discount tiers. |
| Name | Data Type | Description |
|---|---|---|
| shipping_methods | array of string | One or more shipping methods that may receive this discount |
| tiers | array of CouponTierPercent | A list of discount tiers. |
| Name | Data Type | Description |
|---|---|---|
| items | array of string | An optional list of items of which a quantity of one or many must be purchased for coupon to be valid. If empty, all items apply toward subtotal amount. |
| tiers | array of CouponTierPercent | A list of discount tiers. |
| Name | Data Type | Description |
|---|---|---|
| discount_amount | number | The amount of subtotal discount |
| items | array of string | A list of items which will receive this discount. |
| Name | Data Type | Description |
|---|---|---|
| discount_percent | number | The percent of subtotal discount |
| subtotal_amount | number | The amount of subtotal required to receive the discount percent |
| Name | Data Type | Description |
|---|---|---|
| discount_amount | number | The amount of discount per item. |
| item_quantity | integer (int32) | The quantity of item purchased (in units) |
| Name | Data Type | Description |
|---|---|---|
| discount_percent | number | The percent of discount per item. |
| item_quantity | integer (int32) | The quantity of item purchased (in units) |
| Name | Data Type | Description |
|---|---|---|
| developer_message | string | A technical message meant to be read by a developer |
| error_code | string | HTTP status code |
| more_info | string | Additional information often a link to additional documentation |
| user_message | string | An end-user friendly message suitable for display to the customer |
| Name | Data Type | Description |
|---|---|---|
| error | Error | Error object if unsuccessful |
| metadata | ResponseMetadata | Meta-data about the response such as payload or paging information |
| success | boolean | Indicates if API call was successful |
| Name | Data Type | Description |
|---|---|---|
| payload_name | string | Payload name |
| result_set | ResultSet | Result set |
| Name | Data Type | Description |
|---|---|---|
| count | integer (int32) | Number of results in this set |
| limit | integer (int32) | Maximum number of results that can be returned in a set |
| more | boolean | True if there are more results to query |
| next_offset | integer (int32) | The next offset that you should query to retrieve more results |
| offset | integer (int32) | Offset of this result set (zero based) |
| total_records | integer (int32) | The total number of records in the result set. May be null if the number is not known and the client should continue iterating as long as more is true. |
| Name | Data Type | Description |
|---|---|---|
| UC-REST-ERROR | string | Contains human readable error message |
| Name | Data Type |
|---|---|
| body | ErrorResponse |
| Name | Data Type | Description |
|---|---|---|
| UC-REST-ERROR | string | Contains human readable error message |
| Name | Data Type |
|---|---|
| body | ErrorResponse |
| Name | Data Type | Description |
|---|---|---|
| UC-REST-ERROR | string | Contains human readable error message |
| Name | Data Type |
|---|---|
| body | ErrorResponse |
| Name | Data Type | Description |
|---|---|---|
| UC-REST-ERROR | string | Contains human readable error message |
| Name | Data Type |
|---|---|
| body | ErrorResponse |
| Name | Data Type | Description |
|---|---|---|
| UC-REST-ERROR | string | Contains human readable error message |
| Name | Data Type |
|---|---|
| body | ErrorResponse |