Discounts

#The discount object

Attributes

• idinteger
  Unique numeric identifier for the customer.
• applies_to_idinteger
  Applied to id of the product or collection where the id is the id of the shopify product or the shopify custom collection id.
• applies_to_product_typestring
  Sets the specific product type the discount applies to.
  Possible values

  ALLONETIMESUBSCRIPTION
• applies_to_resourcestringSCIRCS
  Applied to a specific product or collection.
  Possible values

  shopify_productshopify_collection_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).
  If you're on the SCI Platform, checkout channel will not apply during Shopify checkouts.
• codestring
  The name of the discount.
• created_atdatetime
  The date and time when the discount was created.
• discount_typestring
  The type of discount. Either percentage or fixed_amount.
• durationstring
  Number of times a discount will be automatically re-applied to a new queued charge after its first usage on a successful charge. Values can be: forever will re-apply unlimited times usage_limit number of times will be set in duration_usage_limit single_use it will not re-apply.
• duration_usage_limitinteger
  Specific number of times a discount will be automatically re-applied to a new queued charge after its first usage on a successful charge. *Only used, and is required, when “duration” is set to “usage_limit”.
• 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.
• first_time_customer_restrictionstring
  Discount can be used on checkout for customer that still don’t exist in Recharge database. Default value is null.
• once_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, unless the discount_duration attribute specifies otherwise.
• prerequisite_subtotal_mininteger
  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.
  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.
• times_usedinteger
  Number of times a discount was used by customers at checkout.
• updated_atdatetime
  The date and time when the discount was last updated.
• usage_limitinteger
  Sets the limit on the number of times a discount can be used by all customers.
• valuestring
  The discounted value to be applied.

#Create a discount

Body parameters

• applies_to_idinteger
  Applied to id of the product or collection where the id is the id of the shopify product or the shopify custom collection id.
• applies_to_product_typestring
  Sets the specific product type the discount applies to.
  Possible values

  ALLONETIMESUBSCRIPTION
• applies_to_resourcestringSCI
  Applied to a specific product or collection.
  Possible values

  shopify_productshopify_collection_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).
• codestringRequired
  The name of the discount.
• created_atdatetime
  The date and time when the discount was created.
• discount_typestringRequired
  The type of discount. Either percentage or fixed_amount.
• durationstringRequired
  Number of times a discount will be automatically re-applied to a new queued charge after its first usage on a successful charge. Values can be: forever will re-apply unlimited times usage_limit number of times will be set in duration_usage_limit single_use it will not re-apply.
• duration_usage_limitintegerRequired
  Specific number of times a discount will be automatically re-applied to a new queued charge after its first usage on a successful charge. *Only used, and is required, when “duration” is set to “usage_limit”.
• 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.
• first_time_customer_restrictionstring
  Discount can be used on checkout for customer that still don’t exist in Recharge database. Default value is null.
  Possible values

  nullcustomer_must_not_exist_in_recharge
• once_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, unless the discount_duration attribute specifies otherwise.
• prerequisite_subtotal_mininteger
  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.
  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_limitinteger
  Sets the limit on the number of times a discount can be used by all customers.
• valuestringRequired
  The discounted value to be applied.

#Retrieve a discount

#Update a discount

Body parameters

• channel_settingsstring
  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).
• ends_atdatetime
  The date when the discount will end.
• starts_atdatetime
  The date when the discount will start.
• 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.
  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_limitinteger
  The limit in which a discount can be used.

#Delete a discount

#List discounts

Query parameters

• created_at_maxstring
  Get all discounts created before a specified date.
• created_at_minstring
  Get all discounts created after a specified date.
• discount_codestring
  Search for a particular discount code.
• discount_typestring
  Type of discount. Value can be percentage or fixed_amount.
• 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.
  (default:50) (maximum: 250)
  Default 50Maximum 250
• pagestringDeprecated
  Page to show.
  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 or disabled.
• updated_at_maxstring
  Get all discounts updated before a specified date.
• updated_at_minstring
  Get all discounts updated after a specified date.

#Count discounts

Query parameters

• created_at_maxstring
  Returns the count of discounts created before a specified date.
• created_at_minstring
  Returns the count of discounts created after a specified date.
• discount_typestring
  Returns the count of discounts that are of a given type. Value can be percentage, fixed_amount or shipping.
• statusstring
  Returns the count of discounts with status of enabled or disabled.
• updated_at_maxstring
  Returns the count of discounts updated before a specified date.
• updated_at_minstring
  Returns the count of discounts updated after a specified date.

Response attributes

• countinteger

#Apply a discount to an address

Body parameters

• discount_codestring
  Code of the discount you want to apply to an address.
• discount_idinteger
  Id of the discount you want to apply to an address.

Response attributes

• idinteger
  The unique numeric identifier for the charge.
• address_idinteger
  The customer shipping address the charge is tied to.
• analytics_dataobject
  An object containing analytics data associated with the charge.
  Show child attributesHide child attributes1

  • utm_paramsarray of objects
    An array containing utm_parameters which are commonly used to store the details of an acquisition campaign.
    Show child attributesHide child attributes7

    • utm_campaignstring
      The utm campaign details.
    • 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.
• billing_addressobject
  All the billing information related to the charge.
  Show child attributesHide child attributes10

  • address1string
    Line one of the billing address.
  • address2string
    Line two of the billing address.
  • citystring
    The city of the billing address.
  • companystring
    The company name of the billing address.
  • countrystring
    The country of the billing address.
  • first_namestring
    The first name of the billing address.
  • last_namestring
    The last name of the billing address.
  • phonestring
    The phone number of the billing address.
  • provincestring
    The name of the province or state associated with the billing address.
  • zipstring
    The zip code of the billing address.
• client_detailsobject
  Details of the access method used by the purchaser.
  Show child attributesHide child attributes2

  • browser_ipstring
    The IP address of the buyer as detected in checkout.
  • user_agentstring
    The user agent detected during checkout.
• created_atdatetime
  When the Charge was created.
• customer_hashstring
  The hash of the Customer associated with the charge.
• customer_idstring
  The id of the Customer associated with the charge.
• discount_codesobject
  An array of discounts associated with the charge.
  Show child attributesHide child attributes4

  • recharge_discount_idinteger
    The id of a discount associated with this charge.
  • codestring
    The code of the discount applied on this charge.
  • valuefloat
    The value of the discount applied to the charge.
  • typestring
    The type of the value of the discount applied to the charge (percentage, fixed_amount).
• emailstring
  The email address of the customer.
• first_namestring
  The first name of the customer.
• has_uncommited_changes
  Specifies whether the charge is scheduled for a regeneration (if the subscription related to the charge was updated in the last 5 seconds using “commit_update”:false).
• last_namestring
  The last name of the customer.
• line_itemsarray of objects
  A list of line_item objects, each one containing information about an item in the charge. One line_item per subscription.
  Show child attributesHide child attributes12

  • graminteger
    Weight in gram of the item.
  • imagesobject
    Weight in gram of the item.
    Show child attributesHide child attributes2

    • keystring
      The key for an image associated to the product.
      Possible values

      largemediumoriginalsmall
    • valuestring
      The value of the property
  • original_pricestring
    The original price of the item without discounts or taxes.
  • pricestring
    The price of the item.
  • propertiesarray of objects
    An array of Property object containing customer information for an item.
    Show child attributesHide child attributes2

    • namestring
      The name of the property.
    • valuestring
      The url reference for the image (CDN or other).
  • quantityinteger
    The number of products that were purchased.
  • shopify_product_idinteger
    The unique numeric identifier for the Shopify product in the fulfillment.
  • shopify_variant_idinteger
    The id of the Shopify product variant.
  • skustring
    A unique identifier of the item in the fulfillment.
  • titlestring
    The title of the product.
  • variant_titlestring
    The title of the product variant.
  • subscription_idinteger
    The id of the corresponding Subscription.
• notestring
  Shows the next order in sequence.
• note_attributesarray of objects
  note attributes.
  Show child attributesHide child attributes2

  • namestring
    The name for the note_attribute.
  • valuestring
    The value for the associated note_attribute.
• processor_namestring
  The payment processor used on the charge.
• processed_atdatetime
  The date and time when the transaction was processed.
• scheduled_atdatetime
  When the charge processing will next be attempted.
  If a charge failed to process, scheduled_at remains the initial scheduled date of the processing not the date of the next attempt.
• shipments_countinteger
  The number of successfully processed child orders on the charge.
• shipping_addressobject
  The shipping address of the shipping address.
  Show child attributesHide child attributes10

  • address1string
    Line one of the billing address.
  • address2string
    Line two of the billing address.
  • citystring
    The city of the billing address.
  • companystring
    The company name of the billing address.
  • countrystring
    The country of the billing address.
  • first_namestring
    The first name of the billing address.
  • last_namestring
    The last name of the billing address.
  • phonestring
    The phone number of the billing address.
  • provincestring
    The name of the province or state associated with the billing address.
  • zipstring
    The zip code of the billing address.
• shipping_linesarray of objects
  An array of shipping lines associated with the charge.
  Show child attributesHide child attributes5

  • codestring
    The code associated with the shipping line of the charge.
  • pricestring
    The price of the shipping line.
  • sourcestring
    The source of the shipping line.
  • titlestring
    The title of the shipping line.
  • taxablestring
    A boolean indicating if the shipping line is taxable.
• shopify_order_idinteger
  The unique numeric identifier within Shopify for the charge
• statusstring
  The status of the charge.
  Possible values

  SUCCESSERRORQUEUEDSKIPPEDREFUNDEDPARTIALLY_REFUNDED
• sub_total
  The item price without taxes and discounts. Use subtotal_price instead.
• subtotal_pricestring
  The item price without taxes and shipping.
• tagsarray
  Array of strings used to distinguish specific charges.
• tax_linesarray of objects
  Array of strings used to distinguish specific charges.
  Show child attributesHide child attributes5

  • codestring
    The code associated with the shipping line of the charge.
  • pricestring
    The price of the shipping line.
  • sourcestring
    The source of the shipping line.
  • titlestring
    The title of the shipping line.
  • taxablestring
    A boolean indicating if the shipping line is taxable.
• total_discountsstring
  The sum of the discounts applied to the Charge.
• total_line_items_pricestring
  The sum of all the prices of all the items in the charge.
• total_pricestring
  The sum of all the prices of all the items in the charge, taxes and discounts included (must be positive).
• total_refundsstring
  The sum of all refunds that were made on specific charge.
• total_weightstring
  The sum of all refunds that were made on specific charge.
• transaction_idstring
  The unique alphanumeric identifier of the transaction.
• typestring
  The type of the charge.
  Possible values

  CHECKOUTRECURRING
• updated_atdatetime
  The date and time when the Charge was last updated.
• errorstring
  Error reason as sentence text (typically returned direct from the payment processor). e.g. "Customer needs to update credit card"
• error_typestring
  Structured reason why the charge failed such as CUSTOMER_NEEDS_TO_UPDATE_CARD
• last_charge_attempt_datedatetime
  The date when a charge was last attempted.
• number_times_triedinteger
  Shows how many times an attempt to charge was placed.
• retry_datedate
  The date when the next attempt will be placed.
• shopify_variant_id_not_foundinteger
  Indicates if Recharge was able to find the shopify_variant_id from the charge.

#Apply a discount to a charge

Body parameters

• discount_codestring
  Code of the discount you want to apply to a charge.
• discount_idinteger
  Id of the discount you want to apply to a charge.

Response attributes

• idinteger
  Unique numeric identifier for the Address.
• address1string
  The street associated with the Address.
• address2string
  Any additional information associated with the shipping address.
• cart_notestringBigCommerceCustomRCS
  The note that that will be passed to the note field of Orders made within the Address.
  cart_note is not currently honored when sent to the Shopify contract api (SCI).
• citystring
  The city associated with the shipping address.
• companystring
  The company associated with the shipping address.
• countrystring
  The country associated with the shipping address.
• country_codestring
  The 2-letter country code.
• customer_idinteger
  Unique numeric identifier for the Customer associated with the Address.
• discount_idinteger
  Unique numeric identifier of Discount that is applied on the Address.
• first_namestring
  The customer’s first name associated with the address.
• last_namestring
  The customer’s last name associated with the address.
• note_attributesarray of objects
  Extra information that is added to the order.
  Show child attributesHide child attributes2

  • namestring
    The name for the note_attribute.
  • valuestring
    The value for the associated note_attribute.
• phonestring
  The phone number associated with the address.
• presentment_currencystringSCI
  Presentment currency is the currency used to display prices to the associated on a storefront and at checkout.
  Only set if the currency is different from the store-level currency. Else, will default to store-level currency.
• provincestring
  The state or province associated with the address.
• shipping_lines_overridearray of objects
  Used when shipping rates need to be overridden. If this parameter has value null, rates will be fetched when a related Charge is created or regenerated
  Show child attributesHide child attributes3

  • codestring
    The code of the associated shipping line.
  • pricestring
    The price (in store’s currency) of the associated shipping line.
  • titlestring
    The title of the associated shipping line.
• zipstring
  The zip or postal code associated with the address.
• cart_attributesarray
  Additional information added to an initial order.
  Important: This field will be deprecated. Please use note_attributes instead.
• created_atdatetime
  The date and time when the address was created.
• original_shipping_lines
  Shipping line details.
  Important: This field will be deprecated. Please use shipping_lines_override instead.
• updated_atdatetime
  The date and time when the Address was last updated.

#Remove a discount

Body parameters

• address_idinteger
  Unique numeric identifier for address from which you want to remove the discount.
• charge_idinteger
  Unique numeric identifier of the charge from which you want to remove the discount.

Response attributes

• idinteger
  Unique numeric identifier for the Address.
• address1string
  The street associated with the Address.
• address2string
  Any additional information associated with the shipping address.
• cart_notestringBigCommerceCustomRCS
  The note that that will be passed to the note field of Orders made within the Address.
  cart_note is not currently honored when sent to the Shopify contract api (SCI).
• citystring
  The city associated with the shipping address.
• companystring
  The company associated with the shipping address.
• countrystring
  The country associated with the shipping address.
• country_codestring
  The 2-letter country code.
• customer_idinteger
  Unique numeric identifier for the Customer associated with the Address.
• discount_idinteger
  Unique numeric identifier of Discount that is applied on the Address.
• first_namestring
  The customer’s first name associated with the address.
• last_namestring
  The customer’s last name associated with the address.
• note_attributesarray of objects
  Extra information that is added to the order.
  Show child attributesHide child attributes2

  • namestring
    The name for the note_attribute.
  • valuestring
    The value for the associated note_attribute.
• phonestring
  The phone number associated with the address.
• presentment_currencystringSCI
  Presentment currency is the currency used to display prices to the associated on a storefront and at checkout.
  Only set if the currency is different from the store-level currency. Else, will default to store-level currency.
• provincestring
  The state or province associated with the address.
• shipping_lines_overridearray of objects
  Used when shipping rates need to be overridden. If this parameter has value null, rates will be fetched when a related Charge is created or regenerated
  Show child attributesHide child attributes3

  • codestring
    The code of the associated shipping line.
  • pricestring
    The price (in store’s currency) of the associated shipping line.
  • titlestring
    The title of the associated shipping line.
• zipstring
  The zip or postal code associated with the address.
• cart_attributesarray
  Additional information added to an initial order.
  Important: This field will be deprecated. Please use note_attributes instead.
• created_atdatetime
  The date and time when the address was created.
• original_shipping_lines
  Shipping line details.
  Important: This field will be deprecated. Please use shipping_lines_override instead.
• updated_atdatetime
  The date and time when the Address was last updated.