Skip to content

[PR-25200] [DOCS] Update Shopfiy coupon auto-sync documentation #414

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bohdan-perekhrest merged 1 commit into from
Nov 10, 2025
Merged

[PR-25200] [DOCS] Update Shopfiy coupon auto-sync documentation #414

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 69 additions & 66 deletions source/advanced_features/shopify_coupons_auto_sync.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
.. _advanced_features/shopify_coupons_auto_sync:

.. meta::
:description: Talkable supports coupon auto-sync for Shopify. This feature allows to avoid manual coupon uploads and/or Shopify Price Rule management.
:description: Talkable supports coupon auto-sync for Shopify. This feature allows to avoid manual coupon uploads and/or Shopify Discount management.

Shopify coupon auto-sync
========================

Talkable supports coupon auto-sync for Shopify. This feature allows the automation of code creation and management of Shopify Price Rules, rather than manual code creation and upload to the Talkable Platform.
Talkable supports coupon auto-sync for Shopify. This feature allows the automation of code creation and management of Shopify Discounts, rather than manual code creation and upload to the Talkable Platform.

.. note::
Shopify coupon auto-sync and :ref:`Coupon Webhook <web_hooks/create_coupon>` can be enabled simultaneously.
Expand All @@ -21,56 +21,58 @@ To enable coupon auto-sync in a coupon list, go to the coupon list edit/create p
If this checkbox is disabled (you are unable to check/uncheck it), it means that your user doesn't have rights for this site or Shopify Integration is not authorized.

.. note::
Talkable uses a Shopify Price Rule ID (if present) to determine where to upload newly generated coupons. It is recommended to leave it blank when creating coupon lists. If blank, Talkable will create a Price Rule based on coupon list configuration and store its ID in the coupon list.
When you try to create a coupon list with a 100% discount you have to provide a Price Rule ID manually. That was made for preventing mistakes in the PriceRule setup.
Talkable uses a Shopify Discount ID (if present) to determine where to upload newly generated coupons. It is recommended to leave it blank when creating coupon lists. If blank, Talkable will create a Discount based on coupon list configuration and store its ID in the coupon list.
When you try to create a coupon list with a 100% discount you have to provide a Discount ID manually. That was made for preventing mistakes in the Discount setup.

Please see **Advanced features** for more information about Shopify Price Rule ID.
Please see **Advanced features** for more information about Shopify Discount ID.


What is Price Rule?
What is a Discount?
~~~~~~~~~~~~~~~~~~~

A price rule is the closest thing to Talkable coupon lists in Shopify. It defines the properties and applicability of associated coupon codes. You can read more on the Shopify site `here <https://shopify.dev/docs/admin-api/rest/reference/discounts/pricerule>`_.
A Discount is the closest thing to Talkable coupon lists in Shopify. It defines the properties and applicability of associated coupon codes. You can read more on the Shopify site `here <https://shopify.dev/docs/api/admin-graphql/latest/objects/DiscountCodeBasic>`_.

What attributes will the auto-generated Price Rule have?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
What attributes will the auto-generated Discount have?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Talkable applies the below coupon list settings onto Price Rule:
Talkable applies the below coupon list settings onto the Discount:

.. container:: ptable

===================== =================================== ======================================
Coupon list attribute Price rule attribute (as in API) Price rule attribute (as in interface)
===================== =================================== ======================================
**Amount** `value` Value
**Discount type** `value_type` Type
**Expiration date** `ends_at` End date
**Minimum subtotal** `prerequisite_subtotal_range` Minimum purchase amount
===================== =================================== ======================================
===================== ======================================== ======================================
Coupon list attribute Discount attribute (as in API) Discount attribute (as in interface)
===================== ======================================== ======================================
**Amount** `customerGets.value` Value
**Discount type** `customerGets.value.percentage` or Type
`customerGets.value.discountAmount`
**Expiration date** `endsAt` End date
**Minimum subtotal** `minimumRequirement.subtotal` Minimum purchase amount
`.greaterThanOrEqualToSubtotal`
===================== ======================================== ======================================

Some other Price Rule attributes that we set when generating Price Rule:
Some other Discount attributes that we set when generating the Discount:

.. container:: ptable

======================== ======================= =============================================
Price Rule attribute Value Attribute effect
======================== ======================= =============================================
`title` e.g. "Talkable Describes Price Rule.
single-use coupons $10"
`target_type` `line_item` The price rule applies to the cart's line
items.
`target_selection` `all` The price rule applies the discount to all
line items in the checkout.
`allocation_method` `across` The calculated discount amount will be
applied across the entitled items.
For example, for a price rule that takes
$15 off, the discount will be applied across
all the entitled items.
`usage_limit` `1` Each discount code can be used exactly once.
`customer_selection` `all` The price rule is valid for all customers.
`starts_at` Time of coupon list The date and time when the price rule starts.
creation
======================== ======================= =============================================
============================= ============================= =============================================
Discount attribute Value Attribute effect
============================= ============================= =============================================
`title` e.g. "Talkable Describes the Discount.
single-use coupons $10"
`customerGets.items` `{ all: true }` The discount applies to all items in
the cart. Can be restricted to specific
products or collections.
`customerGets.value` `{ percentage: 0.1 }` or Discount value - either percentage
`{ discountAmount: {...} }` (0.0-1.0) or fixed amount.
`appliesOncePerCustomer` `false` Allows the customer to use discount
multiple times.
`usageLimit` `1` Each discount code can be used exactly once.
`customerSelection` `{ all: true }` The discount is valid for all customers.
Can be restricted to specific customers
or customer segments.
`startsAt` Time of coupon list The date and time when the discount starts.
creation
============================= ============================= =============================================


Why aren't there any coupons created for my auto-synced list?
Expand All @@ -81,61 +83,62 @@ Auto-sync generates and uploads coupons when there is demand for them. That mean
Advanced features
-----------------

Shopify Price Rule ID
~~~~~~~~~~~~~~~~~~~~~
Shopify Discount ID
~~~~~~~~~~~~~~~~~~~

Talkable allows you to assign a custom Price Rule ID to a coupon list. This might be helpful if you want to deviate from our default Price Rule settings, e.g. restrict codes to a group of customers or group of products.
Talkable allows you to assign a custom Discount ID to a coupon list. This might be helpful if you want to deviate from our default Discount settings, e.g. restrict codes to a group of customers or group of products.

It is recommended to create a new Price Rule in Shopify if there is a need to use a custom one, instead of editing the Price Rule generated by Talkable.
It is recommended to create a new Discount in Shopify if there is a need to use a custom one, instead of editing the Discount generated by Talkable.

.. warning::
Talkable validates the Price Rule attached to a coupon list. There are certain Price Rule attributes that must match the coupon list configuration.
Talkable validates the Discount attached to a coupon list. There are certain Discount attributes that must match the coupon list configuration.
These include:

`allocation_method` - must be "across"
`Applies once per customer` - must be `false` (amount split across items)

`value` - must correspond to coupon list amount
`Value` - must correspond to coupon list amount

`value_type` - must correspond to coupon list type
`Type` - must correspond to coupon list type

`ends_at` - must be greater than or equal to coupon list expiration (and absent if coupon list has no expiration)
`Ends At` - must be greater than or equal to coupon list expiration (and absent if coupon list has no expiration)

`prerequisite_subtotal_range` - must match coupon list minimum subtotal
`Minimum Subtotal` - must match coupon list minimum subtotal

If the Price Rule passes validation, it can be attached to a coupon list and will be used as a new destination for all the coupons created from that moment on.
If the Discount passes validation, it can be attached to a coupon list and will be used as a new destination for all the coupons created from that moment on.

.. note::
All previously generated coupons will retain the attributes of the Price Rule that was used at the point at which they were created (auto-synced).
All previously generated coupons will retain the attributes of the Discount that was used at the point at which they were created (auto-synced).

Shopify Price Rule Changed Email Notification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Shopify Discount Changed Email Notification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you modify a Price Rules on Shopify, it could make them incompatible with the coupon lists they are attached to. In order to find out about such changes as early as possible, we have a daily monitoring job that checks that Price Rules have no critical differences from respective coupon lists.
If you modify a Discount on Shopify, it could make them incompatible with the coupon lists they are attached to. In order to find out about such changes as early as possible, we have a daily monitoring job that checks that Discounts have no critical differences from respective coupon lists.

Attributes that are checked in this job are the following:

- `allocation_method` - must always be "across"
- `usage_limit` - must always be 1
- `value` - must correspond to coupon list amount
- `value_type` - must correspond to coupon list type
- `ends_at` - must be greater than or equal to coupon list expiration (and absent if coupon list has no expiration)
- `prerequisite_subtotal_range` - must match coupon list minimum subtotal

- `customerGets.value.appliesOnEachItem` - must always be `false`
- `usageLimit` - must always be 1
- `customerGets.value` - must correspond to coupon list amount
- `customerGets.value.percentage` or `customerGets.value.discountAmount` - must correspond to coupon list type
- `endsAt` - must be greater than or equal to coupon list expiration (and absent if coupon list has no expiration)

If any of these attributes differ from what they are expected to be and Talkable cannot fix that by updating a coupon list (see **Coupon list sync**), Talkable sends an email notification.

Once the Price Rule becomes critically different from the coupon list it is assigned to, the coupon list is no longer editable. Please fix the issues listed in the email notification to remedy this situation.
Once the Discount becomes critically different from the coupon list it is assigned to, the coupon list is no longer editable. Please fix the issues listed in the email notification to remedy this situation.

Coupon list sync
~~~~~~~~~~~~~~~~

Talkable tries to keep up with the Price Rules assigned to coupon lists when/if Price Rules change.
Talkable tries to keep up with the Discounts assigned to coupon lists when/if Discounts change.

As long as the Price Rule is otherwise valid for a coupon list, we update the coupon list’s:
As long as the Discount is otherwise valid for a coupon list, we update the coupon list's:

- **expiration date** - only if Price Rule end date is further in the future (or absent)
- **expiration date** - only if Discount end date is further in the future (or absent)
- **minimum subtotal**
- **entitled products**
- **entitled collections**

.. note::
If there are any other changes in the Price Rule that make it not suitable for a certain coupon list, we won’t sync the coupon list. In this case, a Shopify Price Rule Changed Email Notification will be delivered and action will be required to fix the issue.
If there are any other changes in the Discount that make it not suitable for a certain coupon list, we won't sync the coupon list. In this case, a Shopify Discount Changed Email Notification will be delivered and action will be required to fix the issue.

This sync is performed daily. Do not expect an immediate change to be reflected after a Price Rule update.
This sync is performed daily. Do not expect an immediate change to be reflected after a Discount update.