Discounts

#The discount object

Attributes

• idinteger
  Unique numeric identifier for the discount in Recharge.
• application_methodstring · nullableNew
  How the discount is applied. code discounts are applied with a discount code and automatic discounts are applied without one.
  Possible values

  codeautomatic
• applies_toobject
  An object encompassing data that limits discount application on the basis of an associated record (such as customer, products, etc.).
  Show child attributesHide child attributes3

  • idsarray
    A list of ids of the type indicated in applies_to.resource for which the discount can be applied. Currently only supports a list with one value.
  • purchase_item_typestring
    An indicator of whether the discount applies to onetimes, subscriptions, or all purchase item types.
    Possible values

    ALLONETIMESUBSCRIPTION
  • resourcestring
    An indicator of the type of resource to which applies_to_id refers.
    Possible values

    shopify_productshopify_collection_idcollection_id
• applies_to_existing_addressesbooleanNew
  Whether the discount applies to addresses that already exist. Can only be false for automatic discounts.
• channel_settingsobject
  A list of channel objects containing information regarding discount behaviors for each.
  If you're on the SCI Platform, checkout channel will not apply during Shopify checkouts.
  Show child attributesHide child attributes4

  • apiobject
    An object containing api channel settings.
    Show child attributesHide child attributes1

    • can_applyboolean
      A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).
      Default true
  • customer_portalobject
    An object containing customer portal channel settings.
    Show child attributesHide child attributes1

    • can_applyboolean
      A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).
      Default true
  • merchant_portalobject
    An object containing merchant portal channel settings.
    Show child attributesHide child attributes1

    • can_applyboolean
      A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).
      Default true
  • checkout_pageobject
    An object containing checkout channel settings.
    Show child attributesHide child attributes1

    • can_applyboolean
      A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).
      Default true
• codestring
  The code used to apply the discount.
• customer_segmentsarray of objectsNew
  A list of the customer segments linked to the discount. Empty when the discount is not linked to any customer segment.
  Show child attributesHide child attributes11 new

  • customer_segment_idintegerNew
    Unique numeric identifier for the customer segment.
• external_discount_sourcestring · nullableNew
  The external platform that the external_discount_id belongs to.
  Possible values

  big_commerceshopifyrechargeheadlessmagento
• titlestring · nullableNew
  The title of the discount. For automatic discounts the title is also returned as the code.
• created_atdatetime
  The date and time when the discount was created.
• ends_atdatetime
  The expiration timestamp of the discount. Past this time the Discount can no longer be redeemed. After ends_at the status of the Discount will go from active to disabled.
  Recurring discounts applied prior to their ends_at time will still apply.
• external_discount_idobject
  An object containing external ids of the discount.
  Show child attributesHide child attributes1

  • ecommercestring
    The discount id as it appears in the external e-commerce platform.
• prerequisite_subtotal_minstring
  The minimum cart subtotal needed for the discount to be applicable.
• starts_atdatetime
  The date when the discount becomes active.
  When not specified on creation starts_at will default to null which translates into no restrictions.
• statusstring
  The status of the discount. Value can be:
  * enabled discount is active to be applied
  * disabled discount can’t be applied on new purchases. Discount will remain on existing charges to which it has already been applied.
  * fully_disabled discount can no longer be applied. In addition, Discount is removed from every queued charge.
  Possible values

  enableddisabledfully_disabled
  disabled and fully_disabled can both be reverted to enabled. However once a Discount has been updated to fully_disabled it will be removed from all Charges it had been applied to. This removal from Charges is irreversible.
• usage_limitsobject
  An object containing limitations on a discount based on usage_counts results
  Show child attributesHide child attributes51 new

  • one_application_per_customerboolean
    The discount can only be used once for a given customer checkout or manually applied once on the customer portal (irrespective of which address). Once applied, it will continue being re-applied to each new charge on the address.
  • first_time_customer_restrictionboolean
    Discount can be used on checkout for customer that still don’t exist in Recharge database.
  • max_subsequent_redemptionsinteger
    The number of Charges the Discount will apply to besides the initial redemption for a given Customer. For example, if you want a discount to apply for 5 consecutive charges max_subsequent_redemptions should be 4.
  • redemptionsinteger
    Sets the limit on the number of times a discount can be used by all customers. Only returned for stores that have legacy discount usage limits enabled.
    Only returned for stores that have legacy discount usage limits enabled.
  • automatic_redemptions_per_customerinteger · nullableNew
    The total number of Charges the Discount applies to for a given Customer. 0 means the discount is single use and null means it applies to all future charges.
• updated_atdatetime
  The date and time when the discount was last updated.
• valuestring
  The discounted value to be applied.
• value_typestring
  Type of discount mechanic.
  Possible values

  fixed_amountpercentageshipping

#Create a discount

Body parameters

• applies_toobject
  An object encompassing data that limits discount application on the basis of an associated record (such as customer, products, etc.)
  Show child attributesHide child attributes3

  • idsarray
    A list of ids of the type indicated in applies_to.resource for which the discount can be applied. Currently only supports a list with one value.
  • purchase_item_typestring
    An indicator of whether the discount applies to onetimes, subscriptions, or all purchase item types.
    Possible values

    ALLONETIMESUBSCRIPTION
  • resourcestring
    An indicator of the type of resource to which applies_to_id refers.
    Possible values

    shopify_productshopify_collection_idcollection_id
• channel_settingsobject
  A list of channel objects containing information regarding discount behaviors for each.
  * can_apply: a boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).
  Show child attributesHide child attributes4

  • apiobject
    An object containing api channel settings.
    Show child attributesHide child attributes1

    • can_applyboolean
      A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).
      Default true
  • customer_portalobject
    An object containing customer portal channel settings.
    Show child attributesHide child attributes1

    • can_applyboolean
      A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).
      Default true
  • merchant_portalobject
    An object containing merchant portal channel settings.
    Show child attributesHide child attributes1

    • can_applyboolean
      A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).
      Default true
  • checkout_pageobject
    An object containing checkout channel settings.
    Show child attributesHide child attributes1

    • can_applyboolean
      A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).
      Default true
• codestringRequired
  The code used to apply the discount.
• ends_atdatetime
  The expiration timestamp of the discount. Past this time the Discount can no longer be redeemed. After ends_at the status of the Discount will go from active to disabled.
  Recurring discounts applied prior to their ends_at time will still apply.
• external_discount_idobjectNew
  An object containing external ids of the discount.
  Show child attributesHide child attributes11 new

  • ecommercestringNew
    The discount id as it appears in the external e-commerce platform. Maximum 188 characters.
• external_discount_sourcestringNew
  The external platform that the external_discount_id belongs to. The combination of external_discount_source and external_discount_id must be unique.
  Possible values

  big_commerceshopifyrechargeheadlessmagento
• prerequisite_subtotal_minstring
  The minimum cart subtotal needed for the discount to be applicable.
• starts_atdatetime
  The date when the discount becomes ACTIVE.
  When not specified on creation starts_at will default to null which translates into no restrictions.
• statusstring
  The status of the discount.
  Possible values

  enableddisabled
• titlestringNew
  The title of the discount. Maximum 255 characters.
• usage_limitsobject
  Sets the limit on the number of times a discount can be used by all customers.
  Show child attributesHide child attributes51 new

  • one_application_per_customerboolean
    The discount can only be used once for a given customer checkout or manually applied once on the customer portal (irrespective of which address). Once applied, it will continue being re-applied to each new charge on the address.
  • first_time_customer_restrictionboolean
    Discount can be used on checkout for customer that still don’t exist in Recharge database.
  • max_subsequent_redemptionsinteger
    The number of Charges the Discount will apply to besides the initial redemption for a given Customer. For example, if you want a discount to apply for 5 consecutive charges max_subsequent_redemptions should be 4.
  • redemptionsinteger
    Sets the limit on the number of times a discount can be used by all customers. Only accepted for stores that have legacy discount usage limits enabled; otherwise the value is ignored.
    Only accepted for stores that have legacy discount usage limits enabled.
    The redemptions is not enabled by default. Contact us to enable support for this attribute.
  • automatic_redemptions_per_customerinteger · nullableNew
    The total number of Charges the Discount applies to for a given Customer. 0 or 1 makes the discount single use and null applies it to all future charges. Ignored when max_subsequent_redemptions is also passed.
• valuestringRequired
  The discounted value to be applied.
• value_typestringRequired
  The discount type.
  Possible values

  fixed_amountpercentageshipping

#Retrieve a discount

#Update a discount

Body parameters

• applies_toobject
  An object encompassing data that limits discount application on the basis of an associated record (such as customer, products, etc.)
  Show child attributesHide child attributes3

  • idsarray
    A list of ids of the type indicated in applies_to.resource for which the discount can be applied. Currently only supports a list with one value.
  • purchase_item_typestring
    An indicator of whether the discount applies to onetimes, subscriptions, or all purchase item types.
    Possible values

    ALLONETIMESUBSCRIPTION
  • resourcestring
    An indicator of the type of resource to which applies_to_id refers.
    Possible values

    shopify_productshopify_collection_idcollection_id
• channel_settingsobject
  A list of channel objects containing information regarding discount behaviors for each.
  * can_apply: a boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).
  Show child attributesHide child attributes4

  • apiobject
    An object containing api channel settings.
    Show child attributesHide child attributes1

    • can_applyboolean
      A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).
      Default true
  • customer_portalobject
    An object containing customer portal channel settings.
    Show child attributesHide child attributes1

    • can_applyboolean
      A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).
      Default true
  • merchant_portalobject
    An object containing merchant portal channel settings.
    Show child attributesHide child attributes1

    • can_applyboolean
      A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).
      Default true
  • checkout_pageobject
    An object containing checkout channel settings.
    Show child attributesHide child attributes1

    • can_applyboolean
      A boolean to indicate if the discount may be applied using the associated channel (defaults to true for all channels).
      Default true
• codestring
  The code used to apply the discount..
• commitbooleanNew
  Only used when status is set to fully_disabled. If true, the discount is removed from the addresses and queued charges it is applied to before the response is returned. Defaults to false, which removes it in the background.
• ends_atdatetime
  The expiration timestamp of the discount. Past this time the Discount can no longer be redeemed. After ends_at the status of the Discount will go from active to disabled.
  Recurring discounts applied prior to their ends_at time will still apply.
• external_discount_idobjectNew
  An object containing external ids of the discount.
  Show child attributesHide child attributes11 new

  • ecommercestringNew
    The discount id as it appears in the external e-commerce platform. Maximum 188 characters.
• external_discount_sourcestringNew
  The external platform that the external_discount_id belongs to. The combination of external_discount_source and external_discount_id must be unique.
  Possible values

  big_commerceshopifyrechargeheadlessmagento
• prerequisite_subtotal_minstring
  The minimum cart subtotal needed for the discount to be applicable.
• starts_atdatetime
  The date when the discount becomes active.
• statusstring
  The status of the discount. Value can be:
  * enabled discount is active to be applied
  * disabled discount can’t be applied on new purchases. Discount will remain on existing charges to which it has already been applied.
  * fully_disabled discount can no longer be applied. In addition, Discount is removed from every queued charge.
  Possible values

  enableddisabledfully_disabled
  disabled and fully_disabled can both be reverted to enabled. However once a Discount has been updated to fully_disabled it will be removed from all Charges it had been applied to. This removal from Charges is irreversible.
• usage_limitsobject
  Sets the limit on the number of times a discount can be used by all customers.
  Show child attributesHide child attributes51 new

  • one_application_per_customerboolean
    The discount can only be used once for a given customer checkout or manually applied once on the customer portal (irrespective of which address). Once applied, it will continue being re-applied to each new charge on the address.
  • first_time_customer_restrictionboolean
    Discount can be used on checkout for customer that still don’t exist in Recharge database.
  • max_subsequent_redemptionsinteger
    The number of Charges the Discount will apply to besides the initial redemption for a given Customer. For example, if you want a discount to apply for 5 consecutive charges max_subsequent_redemptions should be 4.
  • redemptionsinteger
    Sets the limit on the number of times a discount can be used by all customers. Only accepted for stores that have legacy discount usage limits enabled; otherwise the value is ignored.
    Only accepted for stores that have legacy discount usage limits enabled.
    The redemptions is not enabled by default. Contact us to enable support for this attribute.
  • automatic_redemptions_per_customerinteger · nullableNew
    The total number of Charges the Discount applies to for a given Customer. 0 or 1 makes the discount single use and null applies it to all future charges. Ignored when max_subsequent_redemptions is also passed.
• valuestring
  The discounted value to be applied.
• value_typestring
  The discount type.
  Possible values

  fixed_amountpercentageshipping

#Delete a discount

Body parameters

• commitbooleanNew
  Controls how the discount is removed from the addresses and queued charges it is applied to. If true (default), it is removed before the response is returned. If false, it is removed in the background.

#List discounts

Query parameters

• application_methodstringNew
  Filter discounts by how they are applied.
  Possible values

  codeautomatic
  Only applied for stores that have automatic discounts enabled.
• created_at_maxstring
  Get all discounts created before a specified date.
• created_at_minstring
  Get all discounts created after a specified date.
• cursorstringNew
  Return either the next or previous page of discounts using the next_cursor or previous_cursor value from a previous response. Only limit can be passed together with cursor.
• discount_codestring
  Search for a particular discount code.
• discount_titlestringNew
  Search for a particular discount title. Combine with wildcard_search to match titles that start with the given value.
  Only applied for stores that have automatic discounts enabled.
• discount_typestringNew
  Filter based on type of discount.
  Possible values

  percentagefixed_amountshipping
• sort_bystringNew
  Sort listed Discounts in a specific order. Available sort options: id-asc, id-desc, created_at-asc, created_at-desc, updated_at-asc, updated_at-desc. Defaults to id-desc.
  Possible values

  id-ascid-desccreated_at-asccreated_at-descupdated_at-ascupdated_at-desc
• idsstring
  Filter discounts by id. If passing multiple values, must be comma separated. Non-integer values will result in a 422 error
• limitstring
  Number of results to return.
  Default 50Maximum 250
• pagestringDeprecated
  Page to show.
  Default 1
  Page-based pagination has been deprecated but still available to use for pages up to a 100. If you need data past this point, use cursor pagination.
• statusstring
  Returns all discounts with status enabled, disabled or fully_disabled.
  Possible values

  enableddisabledfully_disabled
• updated_at_maxstring
  Get all discounts updated before a specified date.
• updated_at_minstring
  Get all discounts updated after a specified date.
• wildcard_searchbooleanNew
  If true, discount_code returns all discounts whose code starts with the given value instead of requiring an exact match.

Response attributes

• idinteger
  Unique numeric identifier for the Customer.
• analytics_dataobject
  An object containing analytics data associated with the customer.
  Show child attributesHide child attributes1

  • utm_paramsarray of objects
    An array containing utm_param objects.
    Show child attributesHide child attributes7

    • utm_campaignstring
      The UTM campaign.
    • utm_contentstring
      The UTM content.
    • utm_data_sourcestring
      The source of the campaign parameter.
    • utm_sourcestring
      The UTM source.
    • utm_mediumstring
      The UTM medium.
    • utm_termstring
      The UTM term.
    • utm_timestampstring
      The UTM timestamp.
• apply_credit_to_next_recurring_chargeboolean
  A boolean that indicates whether Recharge credits will be applied to the next recurring charge.
• created_atdatetime
  The date and time when the customer was created.
• emailstring
  The email address of the customer.
• external_customer_idobject
  An object containing external ids for the customer record.
  Show child attributesHide child attributes1

  • ecommercestring
    The customer ID as it appears in the external e-commerce platform.
• first_charge_processed_atdatetime
  Date when first charge was processed for the customer.
• first_namestring
  The customer’s first name.
• has_payment_method_in_dunningboolean
  A boolean that indicates if the customer has a payment method that is in dunning (failed charge).
• has_valid_payment_methodboolean
  Is the payment method valid or not.
• hashstring
  The unique string identifier used in a customers portal link.
• last_namestring
  The customer’s last name.
• phonestring
  The customer's phone number.
• subscriptions_active_countinteger
  The number of active subscriptions on addresses associated with the customer.
• subscriptions_total_countinteger
  The total number of subscriptions created on addresses associated with the customer.
• subscription_related_charge_streakinteger
  The number of consecutive subscription-related charges processed for this customer, while they retain at least one active subscription. When all subscriptions for this customer are cancelled or expired, this value will reset to zero.
• tax_exemptboolean
  Whether the customer tax exempt or not.
• updated_atdatetime
  The date and time when the customer was last updated.