From 585e494190a2cf2c3c3b00317db942d68468c2c4 Mon Sep 17 00:00:00 2001 From: rahinisrinivas Date: Wed, 21 Aug 2024 11:11:14 -0400 Subject: [PATCH 01/22] First time shopper coupon code. --- .../create-first-time-shopper-code.md | 97 +++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 docs/promotions-builder/promotions-builder-codes/create-first-time-shopper-code.md diff --git a/docs/promotions-builder/promotions-builder-codes/create-first-time-shopper-code.md b/docs/promotions-builder/promotions-builder-codes/create-first-time-shopper-code.md new file mode 100644 index 00000000..0f7f648b --- /dev/null +++ b/docs/promotions-builder/promotions-builder-codes/create-first-time-shopper-code.md @@ -0,0 +1,97 @@ +--- +title: Create First-time Shopper's Coupon Code +nav_label: Create First-time Shopper's Coupon Code +sidebar_position: 10 +--- + +First-time shopper is a shopper who has not completed any purchases or authorized orders with the store. + +:::note +- Orders without payment transactions do not count as completed purchases. +- Canceling or refunding an order does not reinstate first-time shopper status. +::: + +## `POST` Create First-time Shopper's Coupon Code + +```http +https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes +``` + +## Parameters + +### Path parameters + +| Name | Required | Type | Description | +|:-----|:---------|:---------|:---------------------------------| +| `promotionID` | Required | `string` | The unique identifier of the promotion. | + +### Headers + +| Name | Required | Type | Description | +|:----------------|:---------|:---------|:-------------------------------------| +| `Authorization` | Required | `string` | The Bearer token required to get access to the API. | + +### Body + +| Name | Required | Type | Description | +|:---------------|:---------|:----------|:-------------------------------------| +| `type` | Required | `string` | Specifies the type of the resource. The type of resource for promotions is `promotion_codes`. | +| `codes` | Required | `array` | Specifies the code details in an array of objects. | +| `codes[].code` | Required | `string` | Specifies the string to use as a code for the promotion. | +| `is_for_new_shopper` | Optional | `boolean` | Indicates whether the coupon is for first-time shoppers. If set to `true`, the discount applies only if the shopper has never made a payment for an order in the store. If `false` or not provided, the discount applies to all shoppers. | + +## Request Example + +```bash +curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes \ + -H "Authorization: Bearer XXXX" \ + -H "Content-Type: application/json" \ + -d $ { + "data":{ + "type": "promotion_codes", + "codes": [ + { + "code": "first_time", + "is_for_new_shopper": true + } + ] + } + } +``` + +## Response Example + +`201 Created` + +```json +{ + "data": [ + { + "id": "7ba5cd3d-a6dc-4745-97e6-3957f8c050df", + "code": "first_time", + "is_for_new_shopper": true + } + ] +} +``` + +## Errors + +The following error is returned when you attempt to create a code with `uses` or `user` parameters: + +```json +{ + "errors": [ + { + "status": 400, + "source": "", + "title": "Invalid Code", + "detail": "Code - first_time_uses can't have limited uses or assigned to users since it's for first time shoppers." + } + ] +} +``` + + + + \ No newline at end of file From 8b0009864f0eb367a99318a489aefdbfcc97834a Mon Sep 17 00:00:00 2001 From: rahinisrinivas Date: Wed, 21 Aug 2024 11:58:06 -0400 Subject: [PATCH 02/22] edits --- .../promotions-builder-codes/create-first-time-shopper-code.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/promotions-builder/promotions-builder-codes/create-first-time-shopper-code.md b/docs/promotions-builder/promotions-builder-codes/create-first-time-shopper-code.md index 0f7f648b..dc14ed9d 100644 --- a/docs/promotions-builder/promotions-builder-codes/create-first-time-shopper-code.md +++ b/docs/promotions-builder/promotions-builder-codes/create-first-time-shopper-code.md @@ -4,11 +4,12 @@ nav_label: Create First-time Shopper's Coupon Code sidebar_position: 10 --- -First-time shopper is a shopper who has not completed any purchases or authorized orders with the store. +A first-time shopper is a shopper who has not completed any purchases or authorized orders with the store. :::note - Orders without payment transactions do not count as completed purchases. - Canceling or refunding an order does not reinstate first-time shopper status. +- A first-time shopper coupon code cannot have limited uses or be assigned to specific users, meaning the code cannot be restricted by the number of times it can be used or tied to a specific customer ID. ::: ## `POST` Create First-time Shopper's Coupon Code From 781ffa8bda233f25760947e63f9f0e163cc9d328 Mon Sep 17 00:00:00 2001 From: David Stover <56250584+davidmoltin@users.noreply.github.com> Date: Mon, 9 Sep 2024 12:15:06 -0400 Subject: [PATCH 03/22] Homepage-change-callout (#262) * Update herosection with new H1 --- src/components/homepage/HeroSection.tsx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/components/homepage/HeroSection.tsx b/src/components/homepage/HeroSection.tsx index 652fb6e1..b95e07b6 100644 --- a/src/components/homepage/HeroSection.tsx +++ b/src/components/homepage/HeroSection.tsx @@ -22,8 +22,8 @@ export default function HeroSection() { Why an iPaaS brings world-class commerce to life → -

- Enterprise-ready commerce +

+ Build modern commerce experiences

Launch faster, solve complex problems, and build world-class From 4469ad4b888133d930ae96353d456fae9b6992a5 Mon Sep 17 00:00:00 2001 From: Jo Date: Thu, 26 Sep 2024 15:58:49 +0100 Subject: [PATCH 04/22] first draft --- .../Release-202-September-4-2024.md | 0 .../Release-203-September-26-2024.md | 27 +++++++++++++++++++ 2 files changed, 27 insertions(+) rename changelog/Studio-Release-Notes/{2023 => }/Release-202-September-4-2024.md (100%) create mode 100644 changelog/Studio-Release-Notes/Release-203-September-26-2024.md diff --git a/changelog/Studio-Release-Notes/2023/Release-202-September-4-2024.md b/changelog/Studio-Release-Notes/Release-202-September-4-2024.md similarity index 100% rename from changelog/Studio-Release-Notes/2023/Release-202-September-4-2024.md rename to changelog/Studio-Release-Notes/Release-202-September-4-2024.md diff --git a/changelog/Studio-Release-Notes/Release-203-September-26-2024.md b/changelog/Studio-Release-Notes/Release-203-September-26-2024.md new file mode 100644 index 00000000..88630f0d --- /dev/null +++ b/changelog/Studio-Release-Notes/Release-203-September-26-2024.md @@ -0,0 +1,27 @@ +--- +title: Studio Release 203 | September 26, 2024 +date: 2024-09-26 +tags: + - Studio +--- + +#### Overview + +Mainly bug fixes in this release. + +#### Complete List of Resolved Items + +#### Exporting to CSV + +* **Bug** - Fixed an issue where exporting to a CSV file was not working. + +#### Style Guide + +* **Bug** - Fixed an issue where large quote font on a component did not reflect the Style Guide. + +#### Cart Drawer + +* **Bug** - Fixed an issue where free shipping method was applied improperly after checkout. + + + From fb0f3410ca8ab212cb69b139a0e6ff19012c1c88 Mon Sep 17 00:00:00 2001 From: rahinisrinivas <133024071+rahinisrinivas@users.noreply.github.com> Date: Thu, 26 Sep 2024 14:15:19 -0400 Subject: [PATCH 05/22] Update docs for payment info (#296) [Auto] Update docs for 'orders.svc' from commit '4c9d4e6c' in branch 'main' --- openapispecs/cartsorders/OpenAPISpec.yaml | 40 +++++++++++++++++++---- 1 file changed, 33 insertions(+), 7 deletions(-) diff --git a/openapispecs/cartsorders/OpenAPISpec.yaml b/openapispecs/cartsorders/OpenAPISpec.yaml index 5315573b..62d84ce3 100644 --- a/openapispecs/cartsorders/OpenAPISpec.yaml +++ b/openapispecs/cartsorders/OpenAPISpec.yaml @@ -1743,7 +1743,7 @@ paths: put: tags: - Tax Items - summary: Update a TaxItem + summary: Update a Tax Item description: Use this endpoint to update a tax item. operationId: updateATaxItem parameters: @@ -2790,9 +2790,29 @@ paths: post: tags: - Payments - summary: Authorize Setup - description: Authorize setup - operationId: authorizeSetup + summary: Payment Setup + description: | + Depending on the payment gateway, you may have access to different transaction types such as capturing funds immediately or authorizing them for later. For more information, see [Transactions](/docs/api/carts/transactions). + + The following types of payment methods are available depending on the payment gateway: + + - `purchase`: The is the simplest method. The gateway attempts to charge the customer immediately. + - `authorize`: This method authorizes a payment so that funds can be captured later, for example, when an item is dispatched or restocked. + - `purchase_setup`: This method prepares the system for a purchase by verifying payment details without actually charging the customer. For example, a customer adds items to their cart and proceeds to checkout. Before finalizing the purchase, the system runs `purchase_setup` to confirm all payment details, but no funds are transferred until the customer confirms the order. + - `authorize_setup`: This method prepares the system for an authorization-only transaction. This process holds the necessary funds but does not transfer them, ensuring that the customer has sufficient balance for the transaction. It sets up the conditions for a future capture of the authorized funds. For example, a customer places a pre-order for a product that will ship in two weeks. The merchant uses `authorize_setup` to prepare for the payment authorization. This holds the customer's funds to ensure they can cover the purchase but waits to capture the payment until the product ships. This ensures that payment is secured but not collected prematurely. + + :::note + + Split payments can be performed using any methods for any gateway. + + - You can partially pay funds using `purchase` method. The gateway attempts to charge the customer immediately, and the payment status for an order will show `partially_paid` + - You can partially pay for an order using `authorize` method where the order will be marked as `partially_authorized`. The transaction must be completed for the order status to be `partially_authorized`. + - A `purchase_setup` method allows verification of payment details for partial payments without transferring funds until the customer confirms the full order. + - An `authorize_setup` method can be used to hold a partial amount of the total funds, ensuring the customer has enough balance for a future capture. + Until a payment is made neither `purchase_setup` nor `authorize_setup` affects the payment statuses, and the order remains unpaid. For more information about order and payment statuses for split payments, see [Split payments](/docs/api/payments/payment-gateways-introduction#split-payments). + + ::: + operationId: paymentSetup parameters: - name: orderID in: path @@ -2836,9 +2856,15 @@ paths: post: tags: - Payments - summary: Confirm Setup - description: Confirm setup - operationId: confirmSetup + summary: Confirm Payment + description: | + Confirm Payment serves as a mechanism to synchronize transaction information from the third-party payment provider back to our system. This ensures that Composable Commerce accurately reflects the values from the payment provider. + + ### Handling 3D Secure Validations for Stripe Payments + + For Stripe Payments requiring 3D Secure validation, the transaction response will include the `client_parameters` object, which provides credentials to support validation of these payment requests on the payment provider's side. We recommend using the Stripe's client libraries to manage these 3D Secure validations. Once the validation succeeds, proceed with a confirmation request to sync the validated transaction into Composable Commerce and continue with the payment process. + + operationId: confirmPayment parameters: - name: orderID in: path From 38a9dd718e4736ddbe1d2afe07696d3a8bfb68e3 Mon Sep 17 00:00:00 2001 From: rahinisrinivas <133024071+rahinisrinivas@users.noreply.github.com> Date: Fri, 27 Sep 2024 13:34:23 -0400 Subject: [PATCH 06/22] Update getting started builder steps (#297) * Update getting started builder steps * edits * edits * edits * edits * edits --- .../build-first-integration.mdx | 137 ++++++------------ 1 file changed, 42 insertions(+), 95 deletions(-) diff --git a/docs/composer/builder/getting-started/build-first-integration.mdx b/docs/composer/builder/getting-started/build-first-integration.mdx index b55c7079..c500c716 100644 --- a/docs/composer/builder/getting-started/build-first-integration.mdx +++ b/docs/composer/builder/getting-started/build-first-integration.mdx @@ -9,8 +9,7 @@ This tutorial walks you through some basic concepts of integration development. - Fetch data from Commerce. - Learn how data flows between steps of an integration. - Use logical branches to determine what to do with the data. -- Send the data conditionally to the log. -- Fetch some external data and perform an action on the data in Commerce. +- Send the data conditionally to another third-party. ## Integration Overview @@ -18,57 +17,51 @@ The integration you build here retrieves an access token to grant you access to ## Prerequisites -You need to authenticate with your Commerce store using the Commerce API keys. See [Application Keys](/docs/authentication/security#application-keys). You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges. +### Gather Elastic Path Composable Commerce Data -| Commerce API Key | Description | +You will need to create a connection using Elastic Path keys and authorization URL. See [Application Keys](/docs/authentication/security#application-keys). You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges. + +| Option | Description | |:------------------------------------|:---------------------------------------| -| **API Base URL** | Your Commerce API Base URL. | -| **Client ID** | Your Commerce Client ID. | -| **Client Secret** | Your Commerce Client Secret. | +| **API Base URL** | This is the API URL. | +| **Client ID** | Your Store's Client ID. | +| **Client Secret** | Your Store's Client Secret. | ## Create a New Integration 1. In Commerce Manager, go to **COMPOSER** > **Builder**. 1. Select **+ Add integration**. The **Configure new integration** page displays. -1. From **Configure new integration**, select **Blank** > **Start from blank integration**. The **Integration Details** page displays. -1. From **Integration details**, complete the following: - - 1. In **Name**, enter **My First Integration**. - 1. (Optional) In **Category**, enter a category. If you do not enter a category, your integration is displayed in **Uncategorized**. - 1. (Optional) In **Labels**, enter any labels you want to give the integration. - 1. (Optional) In **Description**, enter a brief description for this integration. - 1. Select **Next**. +1. From **Create new integration**, select **Quickstart** > **Build an integration from the ground up**. The **Details** page is displayed. +1. From **Create new integration** details page, provide the **Name**, enter a name **My First Integration** for your integration. +1. select **Webhook** for the trigger and click **Create trigger**. -## Configure the Integration Trigger +## Review the Integration Trigger Most integrations are either scheduled events or webhooks triggered by an Elastic Path [observable event](http://localhost:3000/docs/api/integrations/integrations-introduction#observable-events). For this tutorial, we are using the **Webhook Trigger**. -1. Click **Webhook**. The step is added to the flow. -1. Click the step to display the drawer details. By default the following settings are set. +To see the details of the webhook step, click the **Trigger** step tile to display the drawer details. By default, the following settings are set: - 1. In **Inputs**, **Response Type** is set to **Asynchronous**. - 1. **Response Status Code** is set to **200 OK**. - 1. **Response Content Type** is set to **application/json**. +1. **Response Type** is set to **Asynchronous**. +1. You can optionally set **Response Status Code** to **200 OK**. +1. You can optionally set **Response Content Type** to **application/json**. ## Add Your First Step 1. Click **+** under the **Webhook** step to add a new step. -1. From **Choose component**, select the **Code** component. The **Code** component displays. -1. Select the **Code Block** action. The **Code Block** action is added to the flow. -1. Click the step to display the drawer details. -1. In **Step name**, enter a name for the step, for example, **Get Client Token**. -1. Cick **Inputs**. -1. In **Code** > **edit**, enter the following: +1. From **Add a step**, select the **Code** component. The **Code** component displays. +1. Select the **Code Block** action. Author and run your own code action. The **Code Block** action is added to the flow. +1. Click the step tile to display the drawer details. +1. Select the **Details** tab in the details drawer and enter a name for the step, for example, **Get EPCC Client Token**. +1. Click the **Configure** tab. +1. Click **Edit**, enter the following: ```json - const fetch = require("node-fetch@2.6.1/lib/index.js"); const params = new URLSearchParams(); module.exports = async ({ logger, configVars }, stepResults) => { let base_url = "{{paste the url collected in gather step above}}" let client_id = "{{paste the client id collected in gather step above}}" let client_secret = "{{paste the client secret collected in gather step above}}" - params.append('client_id', client_id); params.append('client_secret', client_secret); params.append('grant_type', 'client_credentials'); @@ -78,79 +71,33 @@ Most integrations are either scheduled events or webhooks triggered by an Elasti var data = await response.json(); return { data }; + }; ``` +1. Click the **Check mark** on the upper right corner of the embedded development dialog. 1. Click **Save**. -1. Close the drawer. - -## Create a Branch Based on the Results - -1. Click **+** under the **Get EPCC Client Token** step to add a new step. -1. From **Choose component**, select the **Branch** component. The **Branch** component displays. -1. Select the **Branch on Expression** action. The **Branch on Expression** action is added to the flow. -1. Click the step to display the drawer details. -1. Click **Inputs**. -1. Click **Condition Inputs** > **Branch Name**, enter a name, for example, **Token Exists**. -1. Click **Field**. The **Field** details are displayed. -1. Click **Reference**. The **Reference Step** must be **Get EPCC Client Token**. -1. Click **Reference Search**. **results** is added to the box. -1. Enter **.access_token** after **results**. The **Reference Search** becomes **results.access_token**. -1. Click **Operator** and select **exists**. -1. Click **Save**. -1. Close the drawer. - -### Log Success if the Access Token is Found - -1. Click **+** under the **Token Exists** step to add a step. -1. From **Choose component**, select the **Log** component. The **Log** component displays. -1. Select the **Write Log Message** action. The **Write Log Message** action is added to the flow. -1. Click the step to display the drawer details. -1. In the **Step Name** box type **Success**. -1. Click **Inputs**. -1. In **Log Level**, select **info**. -1. In **Log Message**, enter the message, for example, **Access Token Found!**. -1. Click **Save**. -1. Close the drawer. - -### Log an Error if the Access Token is not Found - -1. Click **+** under the **Else** step to add a step to handle the secrets not matching. -1. From **Choose component**, select the **Log** component. The **Log** component displays. -1. Select the **Write Log Message** action. The **Write Log Message** action is added to the flow. -1. Click the step to display the drawer details. -1. In the **Step Name** box type "**Failure**" -1. Click **Inputs**. -1. In **Log Level**, select **error**. -1. In **Log Message**, enter the warning message, for example, **Access Token Not Found!** -1. Click **Save**. -1. Close the drawer. +1. To test your code, click **Run** in the lower left to trigger manual execution of your integration. It should say **Running** until each step completed. +1. Select the **Get EPCC Client Token** step in the **Steps** panel to see the results of the code in the right **Output** panel. -### (Optional) Get External Data +This example takes static code and executes a POST to the Commerce API and retrieves the access token and makes that JSON response available to subsequent steps. -The following steps provide an example of how to get data from an external API using the **HTTP** component. This is useful for use cases where there is no component that has the actions that you need to retrieve the data that you want. The steps below describe retrieving details for a random beer from [Punk API](https://punkapi.com/documentation/v2) and logs the data. +## (Optional) Get External Data -1. Add a step that uses the **Random Integer** action from the **Math** component. -1. In **Inputs**, set **Min** to **1** and **Max** to **325**. -1. Add a step that uses the **GET Request** action from the **HTTP** component. -1. Configure the step as follows: +The following steps will generate a number between 1 and 325, and retrieve the details of that Beer from **Sample APIs** open API, and and log the data. - 1. In **Inputs**, click **URL**, and select **Template** tab. - 1. In **Template**, enter **https://api.punkapi.com/v2/beers/**. - 1. From **Add Template Field**, select the **Reference** tab. The **Reference** pane is displayed. - 1. Make sure the **Reference Step** is **Random Integer**. - 1. In **Value Preview**, click **Results**. - 1. Make sure that **Reference Search** is **results**. - 1. In **URL**, make sure that **Template** is `https://api.punkapi.com/v2/beers/Random Integer | results`. - -1. Add a step that uses the **Write Log Message** action from the **Log** component. -1. Configure the step as follows: - - 1. In **Inputs**, select **Log Message**. The **Log Message** pane is displayed. - 1. Select the **Reference** tab. - 1. Make sure the **Reference Step** is **GET Request**. - 1. In **Value Preview**, click **results**. - 1. Make sure that **Log Message** is `GET Request | results`. +1. Click **+** under **Success** Log message step to add a step to generate a random number between 1 and 325. +1. Type **Math** in the search box and select the **Math** component. +1. Search for **Random** in the actions search box and select Random Integer. +1. In the Min input box type **1** and in the Max input box type **325**. +1. Click the **+** under "Random Integer" and search for **HTTP**. +1. Select the **HTTP** component and then choose **Get Request**. +1. Click In the **URL** box, click the **Template** tab and type **https://api.sampleapis.com/beers/stouts/**. +1. To the right of the input box, click the **+** symbol to add a template field. +1. Click the **Reference** tab. + + The **Reference Step** should be **Random Integer**, and then in **Value Preview** double click the word **results**. +1. Finally, click the **+** below the **Get Request** step, seach for **Log** message again, and choose **Write Message** and for the "Log Message" click the **Reference** tab again and select the **results** of the **Get Request** step. ## Test Your Integration -Click **Save & Run Test**. This opens the **Test Runner** dialog and shows the results of the integration test. +Click **Save** in the upper right corner and then **Run** in the lower left once save has completed. This will open the **Test History** dialog and show the results of the integration test. From 6c6ef9e92744b6a7095382ec5b1f3a3fe837ad0f Mon Sep 17 00:00:00 2001 From: rahinisrinivas <133024071+rahinisrinivas@users.noreply.github.com> Date: Fri, 27 Sep 2024 14:45:46 -0400 Subject: [PATCH 07/22] Remove references to branching on builder page (#298) --- .../builder/getting-started/build-first-integration.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/composer/builder/getting-started/build-first-integration.mdx b/docs/composer/builder/getting-started/build-first-integration.mdx index c500c716..c1b4f341 100644 --- a/docs/composer/builder/getting-started/build-first-integration.mdx +++ b/docs/composer/builder/getting-started/build-first-integration.mdx @@ -8,8 +8,7 @@ This tutorial walks you through some basic concepts of integration development. - Fetch data from Commerce. - Learn how data flows between steps of an integration. -- Use logical branches to determine what to do with the data. -- Send the data conditionally to another third-party. +- Send the data to another third-party. ## Integration Overview From 23a61db8986e6a997714913a9a1cb9af95b5d5b8 Mon Sep 17 00:00:00 2001 From: rahinisrinivas Date: Tue, 1 Oct 2024 10:10:24 -0400 Subject: [PATCH 08/22] Update steps for Create Custom Fields --- .../commerce-extension-in-cm.mdx | 36 ++++++++++++------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx b/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx index 1ce69219..54973692 100644 --- a/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx +++ b/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx @@ -8,13 +8,13 @@ sidebar_position: 4 1. Go to **COMMERCE EXTENSIONS > Custom APIs**. 1. Select **Create New**. -1. Fill out the following details in the **Basic Details** section: - 1. In **Name**, enter the the name of the Custom API. It should be between 1 and 255 characters. - 1. In **Description**, enter the description for the Custom API. -1. Fill out the following details in the **Advanced Options** section: - 1. In **API Type**, enter the type of the Custom API. - 1. In **Slug**, enter a unique slug identifier for the Custom API. - 1. (Optional) Under **Settings**, select the checkbox for **Allow UPSERT** so the system can automatically create a new record if it doesn't exist when updating. For more details, see [Upsert Custom API Entries](/guides/How-To/commerce-extensions/create-a-multilocation-inventories-resource#upsert-custom-api-entries). +1. In the **Basic Details** section: + 1. **Name**: Enter the the name of the Custom API in the . It should be between 1 and 255 characters. + 1. **Description**: Provide a description for the Custom API. +1. In the **Advanced Options** section: + 1. **API Type**: Specify the type of the Custom API. + 1. **Slug**: Enter a unique slug identifier for the Custom API. + 1. (Optional) In **Settings**, select the checkbox for **Allow UPSERT** so the system can automatically create a new record if it doesn't exist when updating. For more details, see [Upsert Custom API Entries](/guides/How-To/commerce-extensions/create-a-multilocation-inventories-resource#upsert-custom-api-entries). 1. Select **Create Custom API**. ## Creating Custom Fields @@ -22,15 +22,25 @@ sidebar_position: 4 To create a Custom Field for a Custom API, follow these steps: 1. Go to **COMMERCE EXTENSIONS > Custom APIs**. -1. Click on the target Custom API in the list. -1. Select **Create Field** and choose one of the following options: +1. Select **Create Field** and choose one of these field types: - **String** - **Integer** - **Boolean** -1. Fill out the following details in the **Basic Details** section: - 1. In **Name**, enter the name of the field for the Custom API. It should be between 1 and 255 characters. - 1. In **Description**, enter the description for the field. - 1. In **Slug**, enter a unique slug identifier for the field. + - **Float** +1. In the **Basic Details** section: + 1. **Name**: Enter the field name. It should be between 1 and 255 characters. + 1. **Description**: Provide a description for the field. + 1. **Slug**: Enter a unique slug identifier for the field. +1. (Optional) In **Settings**, select the checkbox for **Allow UPSERT** so the system can automatically create a new record if it doesn't exist when updating. For more details, see [Upsert Custom API Entries](/guides/How-To/commerce-extensions/create-a-multilocation-inventories-resource#upsert-custom-api-entries). +1. In the **Validation** section: + 1. Set the value rules from the drop-down lists: + - **Can be NULL** or **Cannot be NULL** + - **Can be changed** or **Cannot be changed** + - For **String** fields, choose among **Is unique and case sensitive**, **Doesnot need to be unique**, or *Is unique and case insensitive**. + 1. (For **String** fields) Under **Character Limit**, enter **Minimum Length** and **Maximum Length**. + 1. (For **Integer** and **Float** fields) Under **Input Range**, enter **Minimum Value** and **Maximum Value**. + 1. (For **String** fields) In the **Regular Expression** field, enter a less than 1024 character RE2 regular expression to restrict the specific characters that can be stored. + 1. Select **Create Field**. ## Creating Custom API Entries From bb09ac6bf068a095005a1ba05444b316071afbb0 Mon Sep 17 00:00:00 2001 From: rahinisrinivas Date: Tue, 1 Oct 2024 11:03:33 -0400 Subject: [PATCH 09/22] edits --- .../commerce-extension/commerce-extension-in-cm.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx b/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx index 54973692..81f0111c 100644 --- a/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx +++ b/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx @@ -31,10 +31,10 @@ To create a Custom Field for a Custom API, follow these steps: 1. **Name**: Enter the field name. It should be between 1 and 255 characters. 1. **Description**: Provide a description for the field. 1. **Slug**: Enter a unique slug identifier for the field. -1. (Optional) In **Settings**, select the checkbox for **Allow UPSERT** so the system can automatically create a new record if it doesn't exist when updating. For more details, see [Upsert Custom API Entries](/guides/How-To/commerce-extensions/create-a-multilocation-inventories-resource#upsert-custom-api-entries). +1. (Optional) In **Settings**, select the checkbox for **Use as the URL of entry record**. This option is shown only when you select **String** field. 1. In the **Validation** section: 1. Set the value rules from the drop-down lists: - - **Can be NULL** or **Cannot be NULL** + - **Can be NULL** or **Cannot be NULL**. This option is disabled when you select **Use as the URL of entry record**. - **Can be changed** or **Cannot be changed** - For **String** fields, choose among **Is unique and case sensitive**, **Doesnot need to be unique**, or *Is unique and case insensitive**. 1. (For **String** fields) Under **Character Limit**, enter **Minimum Length** and **Maximum Length**. From 6565d6b0a97b1c44774bef28e722982bc2d644e2 Mon Sep 17 00:00:00 2001 From: rahinisrinivas Date: Tue, 1 Oct 2024 11:22:46 -0400 Subject: [PATCH 10/22] edits --- .../commerce-extension/commerce-extension-in-cm.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx b/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx index 81f0111c..4e505433 100644 --- a/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx +++ b/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx @@ -32,11 +32,14 @@ To create a Custom Field for a Custom API, follow these steps: 1. **Description**: Provide a description for the field. 1. **Slug**: Enter a unique slug identifier for the field. 1. (Optional) In **Settings**, select the checkbox for **Use as the URL of entry record**. This option is shown only when you select **String** field. + + When this option is enabled, the value of this field will be used as the URL slug for entries created in the Custom API. This field must be a String, unique, and cannot allow null value. 1. In the **Validation** section: 1. Set the value rules from the drop-down lists: - **Can be NULL** or **Cannot be NULL**. This option is disabled when you select **Use as the URL of entry record**. - **Can be changed** or **Cannot be changed** - - For **String** fields, choose among **Is unique and case sensitive**, **Doesnot need to be unique**, or *Is unique and case insensitive**. + - For **String** fields, choose among **Is unique and case sensitive**, **Doesnot need to be unique**, or *Is unique and case insensitive**. + The **Doesnot need to be unique** option is disabled when you select **Use as the URL of entry record**. 1. (For **String** fields) Under **Character Limit**, enter **Minimum Length** and **Maximum Length**. 1. (For **Integer** and **Float** fields) Under **Input Range**, enter **Minimum Value** and **Maximum Value**. 1. (For **String** fields) In the **Regular Expression** field, enter a less than 1024 character RE2 regular expression to restrict the specific characters that can be stored. From 07f459ef68b0a7b54a35bc9d0bf1208cc901e402 Mon Sep 17 00:00:00 2001 From: rahinisrinivas Date: Tue, 1 Oct 2024 11:24:36 -0400 Subject: [PATCH 11/22] edits --- .../commerce-extension/commerce-extension-in-cm.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx b/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx index 4e505433..8e7645aa 100644 --- a/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx +++ b/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx @@ -31,9 +31,7 @@ To create a Custom Field for a Custom API, follow these steps: 1. **Name**: Enter the field name. It should be between 1 and 255 characters. 1. **Description**: Provide a description for the field. 1. **Slug**: Enter a unique slug identifier for the field. -1. (Optional) In **Settings**, select the checkbox for **Use as the URL of entry record**. This option is shown only when you select **String** field. - - When this option is enabled, the value of this field will be used as the URL slug for entries created in the Custom API. This field must be a String, unique, and cannot allow null value. +1. (Optional) In **Settings**, select the checkbox for **Use as the URL of entry record**. This option is shown only when you select **String** field. When this option is enabled, the value of this field will be used as the URL slug for entries created in the Custom API. This field must be a String, unique, and cannot allow null value. 1. In the **Validation** section: 1. Set the value rules from the drop-down lists: - **Can be NULL** or **Cannot be NULL**. This option is disabled when you select **Use as the URL of entry record**. From 24edd982e8c43f69a0a1f90c983b9fe6afcbe56e Mon Sep 17 00:00:00 2001 From: rahinisrinivas Date: Tue, 1 Oct 2024 12:33:04 -0400 Subject: [PATCH 12/22] update from review --- .../commerce-extension/commerce-extension-in-cm.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx b/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx index 8e7645aa..01a494fb 100644 --- a/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx +++ b/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx @@ -9,7 +9,7 @@ sidebar_position: 4 1. Go to **COMMERCE EXTENSIONS > Custom APIs**. 1. Select **Create New**. 1. In the **Basic Details** section: - 1. **Name**: Enter the the name of the Custom API in the . It should be between 1 and 255 characters. + 1. **Name**: Enter the the name of the Custom API. It should be between 1 and 255 characters. 1. **Description**: Provide a description for the Custom API. 1. In the **Advanced Options** section: 1. **API Type**: Specify the type of the Custom API. @@ -31,7 +31,9 @@ To create a Custom Field for a Custom API, follow these steps: 1. **Name**: Enter the field name. It should be between 1 and 255 characters. 1. **Description**: Provide a description for the field. 1. **Slug**: Enter a unique slug identifier for the field. -1. (Optional) In **Settings**, select the checkbox for **Use as the URL of entry record**. This option is shown only when you select **String** field. When this option is enabled, the value of this field will be used as the URL slug for entries created in the Custom API. This field must be a String, unique, and cannot allow null value. +1. (Optional) In **Settings**, select the checkbox for **Use as the URL of entry record**. This option is shown only when you select **String** field type. + + When this option is enabled, the value of this field will be used as the URL slug for entries created in the Custom API. This field must be a String, unique, and cannot allow null value. The Custom API must not have any existing entries. 1. In the **Validation** section: 1. Set the value rules from the drop-down lists: - **Can be NULL** or **Cannot be NULL**. This option is disabled when you select **Use as the URL of entry record**. From 0ca9e3e5c670464a67146bebc6b2b1a2de683500 Mon Sep 17 00:00:00 2001 From: rahinisrinivas <133024071+rahinisrinivas@users.noreply.github.com> Date: Tue, 1 Oct 2024 12:33:27 -0400 Subject: [PATCH 13/22] Update docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx Co-authored-by: mwan-ep <54115904+mwan-ep@users.noreply.github.com> --- .../commerce-extension/commerce-extension-in-cm.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx b/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx index 01a494fb..5e1b6d83 100644 --- a/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx +++ b/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx @@ -38,7 +38,7 @@ To create a Custom Field for a Custom API, follow these steps: 1. Set the value rules from the drop-down lists: - **Can be NULL** or **Cannot be NULL**. This option is disabled when you select **Use as the URL of entry record**. - **Can be changed** or **Cannot be changed** - - For **String** fields, choose among **Is unique and case sensitive**, **Doesnot need to be unique**, or *Is unique and case insensitive**. + - For **String** fields, choose among **Is unique and case sensitive**, **Does not need to be unique**, or **Is unique and case insensitive**. The **Doesnot need to be unique** option is disabled when you select **Use as the URL of entry record**. 1. (For **String** fields) Under **Character Limit**, enter **Minimum Length** and **Maximum Length**. 1. (For **Integer** and **Float** fields) Under **Input Range**, enter **Minimum Value** and **Maximum Value**. From 2dec2ade7449e2b7f82a656ef09c7bef969523ae Mon Sep 17 00:00:00 2001 From: rahinisrinivas <133024071+rahinisrinivas@users.noreply.github.com> Date: Tue, 1 Oct 2024 12:33:33 -0400 Subject: [PATCH 14/22] Update docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx Co-authored-by: mwan-ep <54115904+mwan-ep@users.noreply.github.com> --- .../commerce-extension/commerce-extension-in-cm.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx b/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx index 5e1b6d83..a937bd72 100644 --- a/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx +++ b/docs/commerce-manager/commerce-extension/commerce-extension-in-cm.mdx @@ -39,7 +39,7 @@ To create a Custom Field for a Custom API, follow these steps: - **Can be NULL** or **Cannot be NULL**. This option is disabled when you select **Use as the URL of entry record**. - **Can be changed** or **Cannot be changed** - For **String** fields, choose among **Is unique and case sensitive**, **Does not need to be unique**, or **Is unique and case insensitive**. - The **Doesnot need to be unique** option is disabled when you select **Use as the URL of entry record**. + The **Does not need to be unique** option is disabled when you select **Use as the URL of entry record**. 1. (For **String** fields) Under **Character Limit**, enter **Minimum Length** and **Maximum Length**. 1. (For **Integer** and **Float** fields) Under **Input Range**, enter **Minimum Value** and **Maximum Value**. 1. (For **String** fields) In the **Regular Expression** field, enter a less than 1024 character RE2 regular expression to restrict the specific characters that can be stored. From 72d5340d1cb3a2e6320eecf8e41e5afd1cbcaf87 Mon Sep 17 00:00:00 2001 From: rahinisrinivas Date: Tue, 1 Oct 2024 15:38:12 -0400 Subject: [PATCH 15/22] edits --- .../create-first-time-shopper-code.md | 6 +++--- .../promotions-builder-codes/create-promotion-codes.mdx | 1 + 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/promotions-builder/promotions-builder-codes/create-first-time-shopper-code.md b/docs/promotions-builder/promotions-builder-codes/create-first-time-shopper-code.md index dc14ed9d..64e7191e 100644 --- a/docs/promotions-builder/promotions-builder-codes/create-first-time-shopper-code.md +++ b/docs/promotions-builder/promotions-builder-codes/create-first-time-shopper-code.md @@ -1,10 +1,10 @@ --- -title: Create First-time Shopper's Coupon Code -nav_label: Create First-time Shopper's Coupon Code +title: Create First time Shopper's Coupon Code +nav_label: Create First time Shopper's Coupon Code sidebar_position: 10 --- -A first-time shopper is a shopper who has not completed any purchases or authorized orders with the store. +A first time shopper is a shopper who has not completed any purchases or authorized orders with the store. :::note - Orders without payment transactions do not count as completed purchases. diff --git a/docs/promotions-builder/promotions-builder-codes/create-promotion-codes.mdx b/docs/promotions-builder/promotions-builder-codes/create-promotion-codes.mdx index 7af8f44a..40e2f567 100644 --- a/docs/promotions-builder/promotions-builder-codes/create-promotion-codes.mdx +++ b/docs/promotions-builder/promotions-builder-codes/create-promotion-codes.mdx @@ -39,6 +39,7 @@ https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes | `codes[].uses` | Optional | `integer` | Specifies the number of times the code can be used. If no value is set, the customer can use the code any number of times. | | `codes[].user` | Optional | `string` | Specifies the customer ID of the shopper who can use the code. For more information, see the [Create a customer](/docs/customer-management/customer-management-api/create-a-customer) section. | | `consume_unit` | Optional | `string` | Specifies whether the code is consumed per application or per checkout. The options are `per_application` or `per_checkout`. The default setting is `per_checkout`. With `per_checkout`, the code is used once for each checkout, regardless of the number of items in the cart. When set to `per_application`, the code is used per application. For cart discounts, each application counts as one usage. For item discounts, each application to either a single quantity or a bundle is counted as one usage. For example, in a store that offers 50% off on SKU1, SKU2, and SKU3, and limits the maximum usage of the promotion code to two, a shopper can apply the promotion up to two quantities. If the cart contains two or more quantities of SKU1, the promotion is applied 2 times to SKU1, and other quantities and items are at the regular price. If the cart contains one quantity of SKU1, one quantity of SKU2, and one quantity of SKU3, the promotion is applied once to SKU1 and once to SKU2. The code usage is applied at checkout and the code is considered consumed at that point. | +| `is_for_new_shopper` | Optional | `boolean` | A flag indicating whether the coupon is for first-time shoppers. If set to `true`, the discount will only apply if the shopper has never made a payment on any order in the store. If set to `false` or left unset, it will be a regualr discount that applies to all shoppers. When this flag is set to true, the coupon cannot have usage limitations or be assigned to specific users. | ## Request Example From 40807e74e22cca020ae085b7bc2990c1150c9dd1 Mon Sep 17 00:00:00 2001 From: rahinisrinivas <133024071+rahinisrinivas@users.noreply.github.com> Date: Wed, 2 Oct 2024 17:53:14 -0400 Subject: [PATCH 16/22] Create a Single Code (#303) * Create a Sing Code * update scenarios * update from review * edit * Update changelog * edits * edits --- changelog/2024/2024-10-2-changelog.md | 10 ++++ .../creating-promotion-codes.mdx | 55 +++++------------- .../promotions-builder/index.mdx | 13 +++++ .../create-first-time-shopper-code.md | 2 +- static/assets/first-time-shopper.png | Bin 0 -> 126925 bytes 5 files changed, 40 insertions(+), 40 deletions(-) create mode 100644 changelog/2024/2024-10-2-changelog.md create mode 100644 static/assets/first-time-shopper.png diff --git a/changelog/2024/2024-10-2-changelog.md b/changelog/2024/2024-10-2-changelog.md new file mode 100644 index 00000000..488bad5c --- /dev/null +++ b/changelog/2024/2024-10-2-changelog.md @@ -0,0 +1,10 @@ +--- +title: 'Added First time shopper coupon code' +date: '2024-10-2' +tags: ['Commerce Manager', 'Promotions Builder'] +hide_blog_post_date: false +--- + +**MAJOR** We have introduced a new feature allowing the creation of promotion codes specifically for first time shoppers, who have not yet completed a purchase with the store. Within Commerce Manager, you can now create a single code and select the option to apply it exclusively for first time shoppers. For more information, see [Creating a Single Code](/docs/commerce-manager/promotions-builder/creating-promotion-codes). + +For details on creating a first time shopper promotion code via the API, see [Create First time Shopper's Coupon Code](/docs/promotions-builder/promotions-builder-codes/create-first-time-shopper-code). \ No newline at end of file diff --git a/docs/commerce-manager/promotions-builder/creating-promotion-codes.mdx b/docs/commerce-manager/promotions-builder/creating-promotion-codes.mdx index b3c53255..ac8847a0 100644 --- a/docs/commerce-manager/promotions-builder/creating-promotion-codes.mdx +++ b/docs/commerce-manager/promotions-builder/creating-promotion-codes.mdx @@ -4,50 +4,28 @@ nav_label: Creating Promotion Codes sidebar_position: 2 --- -## Creating Promotion Codes +### Creating a Single Code 1. Navigate to **STORE > Promotions Builder**. 1. Select the promotion for which you want to create a code. 1. Go to the **Promotion Codes** tab. +1. (Optional) On the right-hand side, select **Add a new promotion code**. - The **Promotion Codes** tab displays the following information: - - - **Code** - - **Maximum uses** - - **User** - - **Actions** - -1. On the right-hand side, select **Add a new promotion code**. -1. Go to one of the following tabs: - - - [**Add a single code**](#creating-a-single-code) - - [**Bulk generate codes**](#creating-bulk-codes) - -1. Enter the required settings. -1. Click **Save**. -1. (Optional) Select the **Delete** icon in the **Actions** column to delete a promotion code. - -### Creating a Single Code - -1. In the **Add a single code** tab, enter the following details: - - - (Optional) **Prepend Value**: Add a prefix value to the generated code. When a code is generated, the specified prepend value is added as a prefix to the code. - - (Optional) **Usage limit type**: Choose the usage limitation type. The options are **Per Checkout** and **Per Application**. The default option is **Per Checkout**. - - (Optional) **Maximum uses**: Enter the maximum number of times a code can be used for this promotion. If no value is set, customers can use the code an unlimited number of times. We recommend you set a value greater than or equal to one. - - (Optional) **Restrict to user**: Enter the customer ID of users who are allowed to use this code. - - **Code**: Define the code for the promotion. You can manually enter the code or click **Generate code**. + The **Add a new promotion code** button is disabled for automatic promotions. To manually create a code, ensure the **Coupon-driven** checkbox is selected while [creating the promotion](/docs/commerce-manager/promotions-builder/creating-a-promotion-in-promotions-builder). +1. In the **Create Single code** tab: + 1. Provide a code in the **Create a code** field. + 1. Choose your audience: + - **Public**: The code is available to everyone. + - **Private**: The code is specific to a particular shopper, so you’ll need to enter their unique identifier. + 1. Set the code type: + - **Regular code**: A standard code that can be used by any shopper. + - **First time Shopper code**: A code for shoppers using it for the first time. This option is only available when you set the audience to **Public**. + 1. Define limitations. Choose either **No limitations** or **Add limitations**. This option is only available when you set the code type to **Regular code**. -1. Click **Save**. + If you select **Add limitations**, specify the **Max code use across all checkouts** to control how many times the code can be used overall. Each time a shopper checkouts, the usage is tracked against this number. -### Creating Bulk Codes - -1. In the **Bulk generate codes** tab, enter the following details: - - - (Optional) **Prepend Value**: Add a prefix value to the generated codes. When codes are generated, the specified prepend value is added as a prefix to each code. - - **Number of codes to generate**: Specify the number of codes to be generated. - - (Optional) **Usage limit type**: Choose the usage limitation type. The options are **Per Checkout** and **Per Application**. The default option is **Per Checkout**. - - (Optional) **Maximum uses**: Enter the maximum number of usages of a code for a promotion. If no value is set, customers can use the code an unlimited number of times. We recommend you set a value greater than or equal to one. -1. Click **Save**. + By default, the Commerce Manager uses the per checkout method. However, if you need to limit usage on a `per_application` basis, you can configure this via the backend. See [Creating Promotion codes](https://elasticpath.dev/docs/promotions-builder/promotions-builder-codes/create-promotion-codes). +1. Select **Save Changes**. ## Searching for a Promotion Code @@ -56,5 +34,4 @@ You can search for a promotion code across all promotions. 1. Go to **STORE > Promotions Builder**. 1. In the **Search coupon code** field, enter the promotion code you are looking for on the **All Promotions** page. - The promotion name associated with the promotion code is displayed. - + The promotion name associated with the promotion code is displayed. \ No newline at end of file diff --git a/docs/commerce-manager/promotions-builder/index.mdx b/docs/commerce-manager/promotions-builder/index.mdx index 9fe88460..e0888329 100644 --- a/docs/commerce-manager/promotions-builder/index.mdx +++ b/docs/commerce-manager/promotions-builder/index.mdx @@ -162,6 +162,19 @@ To set this up in the Promotions Builder: ![Scenario 8](/assets/promotion-example-scenario-7-2.png) +### Scenario 9 - Creating First time Shopper Promotion + +You can offer First Time Shopper Promotion to attract new shoppers to your store. This promotion can be customized with various discount types and rules, but a common approach is to offer a 10% discount on their first order. + +This promotion requires the creation of a public coupon code. You can configure the code so that it is only applicable to shoppers who do not have any prior paid order history in their account. See [Create a Single Code](/docs/commerce-manager/promotions-builder/creating-promotion-codes#creating-a-single-code). + +**Key Conditions**: + +- The shopper must have an account with no previous paid orders. +- The promotion is valid only for their first completed order. + +![Scenario 9](/assets/first-time-shopper.png) + ## Demos