Promo Rules

Promo Rules help you create promo codes for your campaigns. Promo Rules define generic information about promo codes like expiration time, start time, amount of discount being offered etc. For a given promo rule you can define if it’s a percentage discount or a fixed amount and if it applies for the order as a whole or if it’s per item or free shipping. You can then create promo codes for this price rule. Promo codes contain the actual code that is applied at checkout along with some other information. Price Rules have one to many relationship with promo codes.

Subresources

Available methods

    • POST /ecommerce/stores/{store_id}/promo-rules Add a new promo rule to a store

      Add a new promo rule to a store

      POST /ecommerce/stores/{store_id}/promo-rules

      Add a new promo rule to a store.

      Path parameters

      store_id The store id.

      Request body parameters

      id Type: String Title: Promo Rule Foreign ID Read only: false A unique identifier for the promo rule. If Ecommerce platform does not support promo rule, use promo code id as promo rule id. Restricted to UTF-8 characters with max length 50.
      title Type: String Title: Title Read only: false The title that will show up in promotion campaign. Restricted to UTF-8 characters with max length 100.
      description Type: String Title: Description Read only: false The description of a promotion restricted to UTF-8 characters with max length 255.
      starts_at Type: String Title: Promo Start Time Read only: false The date and time when the promotion is in effect in ISO 8601 format.
      ends_at Type: String Title: End Time Read only: false The date and time when the promotion ends. Must be after starts_at and in ISO 8601 format.
      amount Type: Number Title: Amount Read only: false The amount of the promo code discount. If ‘type’ is ‘fixed’, the amount is treated as a monetary value. If ‘type’ is ‘percentage’, amount must be a decimal value between 0.0 and 1.0, inclusive.
      type Type: String Title: Type Read only: false Type of discount. For free shipping set type to fixed.
      Possible Values:
      • fixed
      • percentage
      target Type: String Title: Target Read only: false The target that the discount applies to.
      Possible Values:
      • per_item
      • total
      • shipping
      enabled Type: Boolean Title: Enabled Read only: false Whether the promo rule is currently enabled.
      created_at_foreign Type: String Title: Foreign Create Time Read only: false The date and time the promotion was created in ISO 8601 format.
      updated_at_foreign Type: String Title: Foreign Update Time Read only: false The date and time the promotion was updated in ISO 8601 format.

      Response body parameters

      id Type: String Title: Promo Rule Foreign ID Read only: false A unique identifier for the promo rule. If Ecommerce platform does not support promo rule, use promo code id as promo rule id. Restricted to UTF-8 characters with max length 50.
      title Type: String Title: Title Read only: false The title that will show up in promotion campaign. Restricted to UTF-8 characters with max length 100.
      description Type: String Title: Description Read only: false The description of a promotion restricted to UTF-8 characters with max length 255.
      starts_at Type: String Title: Promo Start Time Read only: false The date and time when the promotion is in effect in ISO 8601 format.
      ends_at Type: String Title: End Time Read only: false The date and time when the promotion ends. Must be after starts_at and in ISO 8601 format.
      amount Type: Number Title: Amount Read only: false The amount of the promo code discount. If ‘type’ is ‘fixed’, the amount is treated as a monetary value. If ‘type’ is ‘percentage’, amount must be a decimal value between 0.0 and 1.0, inclusive.
      type Type: String Title: Type Read only: false Type of discount. For free shipping set type to fixed.
      Possible Values:
      • fixed
      • percentage
      target Type: String Title: Target Read only: false The target that the discount applies to.
      Possible Values:
      • per_item
      • total
      • shipping
      enabled Type: Boolean Title: Enabled Read only: false Whether the promo rule is currently enabled.
      created_at_foreign Type: String Title: Foreign Create Time Read only: false The date and time the promotion was created in ISO 8601 format.
      updated_at_foreign Type: String Title: Foreign Update Time Read only: false The date and time the promotion was updated in ISO 8601 format.
      _links Type: Array Title: Links Read only: true A list of link types and descriptions for the API schema documents.
      Show properties
      rel Type: String Title: Rel Read only: true As with an HTML ‘rel’ attribute, this describes the type of link.
      href Type: String Title: Href Read only: true This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
      method Type: String Title: Method Read only: true The HTTP method that should be used when accessing the URL defined in ‘href’.
      Possible Values:
      • GET
      • POST
      • PUT
      • PATCH
      • DELETE
      • OPTIONS
      • HEAD
      targetSchema Type: String Title: Target Schema Read only: true For GETs, this is a URL representing the schema that the response should conform to.
      schema Type: String Title: Schema Read only: true For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.

      Error response

      type Type: String Title: Problem Type Read only: false An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
      title Type: String Title: Error Title Read only: false A short, human-readable summary of the problem type. It shouldn’t change based on the occurrence of the problem, except for purposes of localization.
      status Type: Integer Title: HTTP Status Code Read only: false The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
      detail Type: String Title: Error Message Read only: false A human-readable explanation specific to this occurrence of the problem. Learn more about errors.
      instance Type: String Title: Instance ID Read only: false A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
    • GET /ecommerce/stores/{store_id}/promo-rules Get information about a store’s promo rules
      GET /ecommerce/stores/{store_id}/promo-rules/{promo_rule_id} Get information about a specific promo rule

      Get information about a store's promo rules

      GET /ecommerce/stores/{store_id}/promo-rules

      Get information about a store’s promo rules.

      Path parameters

      store_id The store id.

      Query string parameters

      fields Type: Array Title: Fields Read only: false A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation.
      exclude_fields Type: Array Title: Exclude Fields Read only: false A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation.
      count Type: Integer Title: Count Read only: true The number of records to return. Default value is 10.
      offset Type: Integer Title: Offset Read only: false The number of records from a collection to skip. Iterating over large collections with this parameter can be slow. Default value is 0.

      Response body parameters

      store_id Type: String Title: Store ID Read only: false The store id.
      promo_rules Type: Array Title: Promo Rules Read only: false An array of objects, each representing promo rules defined for a store.
      Show properties
      id Type: String Title: Promo Rule Foreign ID Read only: false A unique identifier for the promo rule. If Ecommerce platform does not support promo rule, use promo code id as promo rule id. Restricted to UTF-8 characters with max length 50.
      title Type: String Title: Title Read only: false The title that will show up in promotion campaign. Restricted to UTF-8 characters with max length 100.
      description Type: String Title: Description Read only: false The description of a promotion restricted to UTF-8 characters with max length 255.
      starts_at Type: String Title: Promo Start Time Read only: false The date and time when the promotion is in effect in ISO 8601 format.
      ends_at Type: String Title: End Time Read only: false The date and time when the promotion ends. Must be after starts_at and in ISO 8601 format.
      amount Type: Number Title: Amount Read only: false The amount of the promo code discount. If ‘type’ is ‘fixed’, the amount is treated as a monetary value. If ‘type’ is ‘percentage’, amount must be a decimal value between 0.0 and 1.0, inclusive.
      type Type: String Title: Type Read only: false Type of discount. For free shipping set type to fixed.
      Possible Values:
      • fixed
      • percentage
      target Type: String Title: Target Read only: false The target that the discount applies to.
      Possible Values:
      • per_item
      • total
      • shipping
      enabled Type: Boolean Title: Enabled Read only: false Whether the promo rule is currently enabled.
      created_at_foreign Type: String Title: Foreign Create Time Read only: false The date and time the promotion was created in ISO 8601 format.
      updated_at_foreign Type: String Title: Foreign Update Time Read only: false The date and time the promotion was updated in ISO 8601 format.
      _links Type: Array Title: Links Read only: true A list of link types and descriptions for the API schema documents.
      Show properties
      rel Type: String Title: Rel Read only: true As with an HTML ‘rel’ attribute, this describes the type of link.
      href Type: String Title: Href Read only: true This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
      method Type: String Title: Method Read only: true The HTTP method that should be used when accessing the URL defined in ‘href’.
      Possible Values:
      • GET
      • POST
      • PUT
      • PATCH
      • DELETE
      • OPTIONS
      • HEAD
      targetSchema Type: String Title: Target Schema Read only: true For GETs, this is a URL representing the schema that the response should conform to.
      schema Type: String Title: Schema Read only: true For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.
      total_items Type: Integer Title: Item Count Read only: false The total number of items matching the query regardless of pagination.
      _links Type: Array Title: Links Read only: true A list of link types and descriptions for the API schema documents.
      Show properties
      rel Type: String Title: Rel Read only: true As with an HTML ‘rel’ attribute, this describes the type of link.
      href Type: String Title: Href Read only: true This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
      method Type: String Title: Method Read only: true The HTTP method that should be used when accessing the URL defined in ‘href’.
      Possible Values:
      • GET
      • POST
      • PUT
      • PATCH
      • DELETE
      • OPTIONS
      • HEAD
      targetSchema Type: String Title: Target Schema Read only: true For GETs, this is a URL representing the schema that the response should conform to.
      schema Type: String Title: Schema Read only: true For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.

      Error response

      type Type: String Title: Problem Type Read only: false An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
      title Type: String Title: Error Title Read only: false A short, human-readable summary of the problem type. It shouldn’t change based on the occurrence of the problem, except for purposes of localization.
      status Type: Integer Title: HTTP Status Code Read only: false The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
      detail Type: String Title: Error Message Read only: false A human-readable explanation specific to this occurrence of the problem. Learn more about errors.
      instance Type: String Title: Instance ID Read only: false A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.

      Get information about a specific promo rule

      GET /ecommerce/stores/{store_id}/promo-rules/{promo_rule_id}

      Get information about a specific promo rule.

      Path parameters

      store_id The store id.
      promo_rule_id The id for the promo rule of a store.

      Query string parameters

      fields Type: Array Title: Fields Read only: false A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation.
      exclude_fields Type: Array Title: Exclude Fields Read only: false A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation.

      Response body parameters

      id Type: String Title: Promo Rule Foreign ID Read only: false A unique identifier for the promo rule. If Ecommerce platform does not support promo rule, use promo code id as promo rule id. Restricted to UTF-8 characters with max length 50.
      title Type: String Title: Title Read only: false The title that will show up in promotion campaign. Restricted to UTF-8 characters with max length 100.
      description Type: String Title: Description Read only: false The description of a promotion restricted to UTF-8 characters with max length 255.
      starts_at Type: String Title: Promo Start Time Read only: false The date and time when the promotion is in effect in ISO 8601 format.
      ends_at Type: String Title: End Time Read only: false The date and time when the promotion ends. Must be after starts_at and in ISO 8601 format.
      amount Type: Number Title: Amount Read only: false The amount of the promo code discount. If ‘type’ is ‘fixed’, the amount is treated as a monetary value. If ‘type’ is ‘percentage’, amount must be a decimal value between 0.0 and 1.0, inclusive.
      type Type: String Title: Type Read only: false Type of discount. For free shipping set type to fixed.
      Possible Values:
      • fixed
      • percentage
      target Type: String Title: Target Read only: false The target that the discount applies to.
      Possible Values:
      • per_item
      • total
      • shipping
      enabled Type: Boolean Title: Enabled Read only: false Whether the promo rule is currently enabled.
      created_at_foreign Type: String Title: Foreign Create Time Read only: false The date and time the promotion was created in ISO 8601 format.
      updated_at_foreign Type: String Title: Foreign Update Time Read only: false The date and time the promotion was updated in ISO 8601 format.
      _links Type: Array Title: Links Read only: true A list of link types and descriptions for the API schema documents.
      Show properties
      rel Type: String Title: Rel Read only: true As with an HTML ‘rel’ attribute, this describes the type of link.
      href Type: String Title: Href Read only: true This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
      method Type: String Title: Method Read only: true The HTTP method that should be used when accessing the URL defined in ‘href’.
      Possible Values:
      • GET
      • POST
      • PUT
      • PATCH
      • DELETE
      • OPTIONS
      • HEAD
      targetSchema Type: String Title: Target Schema Read only: true For GETs, this is a URL representing the schema that the response should conform to.
      schema Type: String Title: Schema Read only: true For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.

      Error response

      type Type: String Title: Problem Type Read only: false An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
      title Type: String Title: Error Title Read only: false A short, human-readable summary of the problem type. It shouldn’t change based on the occurrence of the problem, except for purposes of localization.
      status Type: Integer Title: HTTP Status Code Read only: false The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
      detail Type: String Title: Error Message Read only: false A human-readable explanation specific to this occurrence of the problem. Learn more about errors.
      instance Type: String Title: Instance ID Read only: false A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
    • PATCH /ecommerce/stores/{store_id}/promo-rules/{promo_rule_id} Update a promo rule. Please note, when a promo rule is updated, the new property/properties will apply to all the promo codes that share this promo_rule_id.

      Update a promo rule. Please note, when a promo rule is updated, the new property/properties will apply to all the promo codes that share this promo_rule_id.

      PATCH /ecommerce/stores/{store_id}/promo-rules/{promo_rule_id}

      Update a promo rule.

      Path parameters

      store_id The store id.
      promo_rule_id The id for the promo rule of a store.

      Request body parameters

      title Type: String Title: Title Read only: false The title that will show up in promotion campaign. Restricted to UTF-8 characters with max length 100.
      description Type: String Title: Description Read only: false The description of a promotion restricted to UTF-8 characters with max length 255.
      starts_at Type: String Title: Promo Start Time Read only: false The date and time when the promotion is in effect in ISO 8601 format.
      ends_at Type: String Title: End Time Read only: false The date and time when the promotion ends. Must be after starts_at and in ISO 8601 format.
      amount Type: Number Title: Amount Read only: false The amount of the promo code discount. If ‘type’ is ‘fixed’, the amount is treated as a monetary value. If ‘type’ is ‘percentage’, amount must be a decimal value between 0.0 and 1.0, inclusive.
      type Type: String Title: Type Read only: false Type of discount. For free shipping set type to fixed.
      Possible Values:
      • fixed
      • percentage
      target Type: String Title: Target Read only: false The target that the discount applies to.
      Possible Values:
      • per_item
      • total
      • shipping
      enabled Type: Boolean Title: Enabled Read only: false Whether the promo rule is currently enabled.
      created_at_foreign Type: String Title: Foreign Create Time Read only: false The date and time the promotion was created in ISO 8601 format.
      updated_at_foreign Type: String Title: Foreign Update Time Read only: false The date and time the promotion was updated in ISO 8601 format.

      Response body parameters

      id Type: String Title: Promo Rule Foreign ID Read only: false A unique identifier for the promo rule. If Ecommerce platform does not support promo rule, use promo code id as promo rule id. Restricted to UTF-8 characters with max length 50.
      title Type: String Title: Title Read only: false The title that will show up in promotion campaign. Restricted to UTF-8 characters with max length 100.
      description Type: String Title: Description Read only: false The description of a promotion restricted to UTF-8 characters with max length 255.
      starts_at Type: String Title: Promo Start Time Read only: false The date and time when the promotion is in effect in ISO 8601 format.
      ends_at Type: String Title: End Time Read only: false The date and time when the promotion ends. Must be after starts_at and in ISO 8601 format.
      amount Type: Number Title: Amount Read only: false The amount of the promo code discount. If ‘type’ is ‘fixed’, the amount is treated as a monetary value. If ‘type’ is ‘percentage’, amount must be a decimal value between 0.0 and 1.0, inclusive.
      type Type: String Title: Type Read only: false Type of discount. For free shipping set type to fixed.
      Possible Values:
      • fixed
      • percentage
      target Type: String Title: Target Read only: false The target that the discount applies to.
      Possible Values:
      • per_item
      • total
      • shipping
      enabled Type: Boolean Title: Enabled Read only: false Whether the promo rule is currently enabled.
      created_at_foreign Type: String Title: Foreign Create Time Read only: false The date and time the promotion was created in ISO 8601 format.
      updated_at_foreign Type: String Title: Foreign Update Time Read only: false The date and time the promotion was updated in ISO 8601 format.
      _links Type: Array Title: Links Read only: true A list of link types and descriptions for the API schema documents.
      Show properties
      rel Type: String Title: Rel Read only: true As with an HTML ‘rel’ attribute, this describes the type of link.
      href Type: String Title: Href Read only: true This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
      method Type: String Title: Method Read only: true The HTTP method that should be used when accessing the URL defined in ‘href’.
      Possible Values:
      • GET
      • POST
      • PUT
      • PATCH
      • DELETE
      • OPTIONS
      • HEAD
      targetSchema Type: String Title: Target Schema Read only: true For GETs, this is a URL representing the schema that the response should conform to.
      schema Type: String Title: Schema Read only: true For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.

      Error response

      type Type: String Title: Problem Type Read only: false An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
      title Type: String Title: Error Title Read only: false A short, human-readable summary of the problem type. It shouldn’t change based on the occurrence of the problem, except for purposes of localization.
      status Type: Integer Title: HTTP Status Code Read only: false The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
      detail Type: String Title: Error Message Read only: false A human-readable explanation specific to this occurrence of the problem. Learn more about errors.
      instance Type: String Title: Instance ID Read only: false A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
    • DELETE /ecommerce/stores/{store_id}/promo-rules/{promo_rule_id} Delete a promo rule. Please note that when a promo rule is deleted, all the promo codes that share the deleted promo rule’s id will be deleted.

      Delete a promo rule. Please note that when a promo rule is deleted, all the promo codes that share the deleted promo rule's id will be deleted.

      DELETE /ecommerce/stores/{store_id}/promo-rules/{promo_rule_id}

      Delete a promo rule from a store.

      Path parameters

      store_id The store id.
      promo_rule_id The id for the promo rule of a store.

      Error response

      type Type: String Title: Problem Type Read only: false An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
      title Type: String Title: Error Title Read only: false A short, human-readable summary of the problem type. It shouldn’t change based on the occurrence of the problem, except for purposes of localization.
      status Type: Integer Title: HTTP Status Code Read only: false The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
      detail Type: String Title: Error Message Read only: false A human-readable explanation specific to this occurrence of the problem. Learn more about errors.
      instance Type: String Title: Instance ID Read only: false A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.