This is a demo BigCommerce app built from Amplify BigCommerce that can demonstrate the ability for a custom application to utlize the BigCommerce Shipping Provider API to provide shipping rates in checkout. Once this app is deployed, you can register it as a shipping provider for a BigCommerce store as described here: https://developer.bigcommerce.com/api-docs/store-management/shipping/shipping-provider-api
Screenshot of the rate management UI:
This application manages the following AWS resources with Amplify CLI:
- IAM Roles
- CloudFormation Stack
- Lambda Functions
- API Gateways
- Cognito User and Identity Pools
- DynamoDB
- S3
- CloudFront
This is intended for demonstration purposes only.
- The UI is clunky
- Only flat-rate shipping methods are supported
- The Validate Connection Options endpoint is not implemented
- And there are bugs.
This application utilizes AWS Amplify CLI and AWS Amplify JS to deploy a serverless backend to AWS, with a React front end that you can run locally, or later build and publish to an S3 bucket behind CloudFront.
This application stores the BigCommerce Client Secret in AWS Secrets Manager. Amplify CLI does not provision the Secrets Manager resource, some of the steps will be performed in the AWS Console. Environment variables to refer to the Secret, as well as the BigCommerce Client ID, will be manually added as parameters for CloudFormation templates.
For Windows users, Amplify recommends the Windows Subsystem for Linux.
If you do not already have one, you will need to create a BigCommerce store. If necessary navigate to https://www.bigcommerce.com/essentials/ to sign up for a free trial store.
Make sure your user account is the "store owner" account. Only the store owner can install draft apps like the one you're about to register. If you created the trial, your account is automatically the store owner.
This example will walk you through registering a personal app. To register a personal BigCommerce app, you will need:
- App Name: The name of your application.
- Auth Callback URL: The React app hosts the auth callback URL at /oauth -- Example: https://example.com/oauth
- Load Callback URL: The React app hosts the load callback URL at /load -- Example: https://example.com/load
You may use a URL such as https://localhost:3000/oauth to test against the local development server. You may update them later to instead use a permanent CloudFront URL, or a custom domain. You can use tools like Amplify Console or Route 53 to apply a domain to your app.
- Navigate to https://devtools.bigcommerce.com and log into your BigCommerce account
- If necessary, log in with your store owner account.
- Click the Create an App button
- Enter your App Name, then click Create
- Navigate to the Technical tab then enter the Auth Callback URL and Load Callback URLs
| Callback Type | URL |
|---|---|
| Auth | https://localhost:3000/oauth |
| Load | https://localhost:3000/load |
| Uninstall | Leave blank for now |
- Take note of your Auth Callback URL to be used as the REDIRECTURL environment variable in a CloudFormation template.
- Save the app
- Click the View Client ID link to view your Client ID and Client Secret. Take note of those values for use in Lambda environment variables and storage in Secrets Manager respectively.
- Take note of the App ID - it is the numeric value visible in the URL when you edit your app’s details
For more information on BigCommerce apps, check out the BigCommerce documentation.
If you don't already have an AWS account, sign up for a free tier account here: https://aws.amazon.com/free
While this utility was developed and tested within the limits of an AWS Free Tier account, you are responsible for any charges incurred by using the resources created by Amplify
Always follow AWS IAM Best Practices, such as operating from an IAM user rather than your root account.
Install and configure Amplify CLI
$ npm install -g @aws-amplify/cli
$ amplify configure
Store your BigCommerce client secret in AWS Secrets Manager.
- Log in to AWS console
- Click Services, and locate Secrets Manager
- Click the Store a new secret button
- Select Other type of secrets (e.g. API key)
- Enter a Secret key/value pair where the key is an arbitrary key name like "client_secret", and the value is the BigCommerce Client Secret.
You can retrieve the client secret from https://devtools.bigcommerce.com
- Take note of your key to use later as the SECRETKEY environment variable in CloudFormation
- Choose an encryption key, or use the default key
- Click Next
- Enter a Secret name, and optionally provide a description and/or tags
- Take note of the secret name to use later as the SECRETNAME environment variable in CloudFormation templates for Lambda functions
- Click Next
- Select Disable automatic rotation
- Click Next
- Review the configuration, then click Store
- In the Secrets Manager console, click the name of your secret to locate the Secret ARN
- Take note of the Secret ARN to use later as the SECRETARN environment variable in CloudFormation templates for Lambda functions
example format: arn:aws:secretsmanager:{region}:{account}:secret:{secret-name}
For more information, see Secrets Manager documentation.
Clone this repo into your project folder.
npm install
Edit amplify/backend/function/bcApiClient/parameters.json, and make the following replacement:
| Key | Value |
|---|---|
| BCCLIENTID | Your BigCommerce Client ID |
Edit amplify/backend/function/CognitoStoresPreSignup/parameters.json, and make the following replacements:
| Key | Value |
|---|---|
| REDIRECTURL | Your app's Auth Callback URI (example: https://localhost:3000/oauth) |
| BCCLIENTID | Your BigCommerce Client ID |
Edit amplify/backend/function/retrieveSecret/parameters.json, and make the following replacements:
| Key | Value |
|---|---|
| SECRETNAME | Your Secret's name in Secrets Manager (example: bcSecret) |
| SECRETKEY | They key from the key value pair in Secrets Manager (example: client_secret) |
| SECRETARN | The Amazon Resource Name of your Secret in Secrets Manager (example format: arn:aws:secretsmanager:{region}:{account}:secret:{secret-name}) |
In the project folder, run the following
amplify init
Follow the prompts to create a new environment, or use an existing one. Amplify CLI will create the AWS resources needed to deploy the application like a CloudFormation stack, and several IAM roles.
To ensure the React client is only able to authenticate with the custom auth flow, be sure to enable Only allow Custom Authentication (CUSTOM_AUTH_FLOW_ONLY) for the app in the App Clients section of the Cognito User Pool console. See the Security Considerations section of the AWS blog post Customizing Amazon Cognito User Pool Authentication Flows.
Nevertheless, the signUp() method requires both a username and password. To ensure the password is not something easily guessable, the React client randomly generates a password between 16 and 256 characters including both alphanumeric and special characters.
The longest part of the deployment is the CloudFront distribution. If you want to start testing as quickly as possible, consider removing the hosting resource and using the local development server for your Auth and Load Callback URLs. To remove hosting, run the following command in the project folder:
amplify hosting remove
Choose S3AndCloudFront and follow the prompts to remove the hosting resources locally. Then, run the following command to deploy the remaining resources to the cloud, and start the local development server:
amplify serve
Answer Y when prompted to create resources in the cloud
To test the uninstall flow, you will need to also complete the Uninstall Callback URL steps below.
If you previously used amplify hosting remove to remove the hosting resources locally, you will first need to run amplify hosting add to add S3 hosting with CloudFront.
In the project folder, run the following
amplify publish
Answer Y when prompted to create resources in the cloud
Amplify will create a CloudFront distribution with HTTPS URLs for your S3 bucket. Then, it runs the React client’s build command, and upload the artifact to an S3 Bucket. Finally, the CLI will provide you with a URL where you can access the React Client. The URL is also available in src/aws-exports.js as aws_content_delivery_url. Alternatively, you can retrieve it from AWS console.
Edit amplify/backend/function/CognitoStoresPreSignup/parameters.json, and make the following replacements:
| Key | Value |
|---|---|
| REDIRECTURL | Your app's new Auth Callback URL (example: *https://abcdef123456.cloudfront.net/oauth) |
Use the /oauth and /load endpoints on the CloudFront URL to update the Auth and Load Callback URLs in BigCommerce:
- Navigate to https://devtools.bigcommerce.com and log into your BigCommerce account
- If necessary, log in with your store owner account.
- Click the Edit App button
- Navigate to the Technical tab then update the Auth and Load Callback URLs
- Click the Update and Close button
- Retrieve the uninstall callback URL.
- It can be found either the AWS console...
- ...or from src/aws-exports.js where it is the endpoint value for an object in aws_cloud_logic_custom (Example: https://abcd1234.execute-api.region.amazonaws.com/environment).
If you retrieve the URL from the aws-exports.js file, you will need to append
/uninstallto the URL.
- Supply the Uninstall Callback URL to BigCommerce
- Navigate to https://devtools.bigcommerce.com and log into your BigCommerce account
- If necessary, log in with your store owner account.
- Click the Edit App button
- Navigate to the Technical tab then enter the Uninstall Callback URL
- Click the Update and Close button
You will need to supply the Request Shipping Rates URL to BigCommerce so that BigCommerce can invoke the app to supply shipping rates. The sample app utilizes AWS API Gateway to create the endpoint. You can retrieve it the same way you retrieved the Uninstall Callback URL:
- Retrieve the uninstall callback URL.
- It can be found either the AWS console...
- ...or from src/aws-exports.js where it is the endpoint value for an object in aws_cloud_logic_custom (Example: https://abcd1234.execute-api.region.amazonaws.com/environment) named carrierServiceApi.
If you retrieve the URL from the aws-exports.js file, you will need to append
/ratesto the URL.
Follow the steps under Sign Up to request BigCommerce to register the app as a shipping provider: https://developer.bigcommerce.com/api-docs/store-management/shipping/shipping-provider-api#shipping_provider-signup
Note: The example app expects a checkbox/boolean Connection Option that indicates whether the app should return expedited rates. This connection option must be created when the app is registered with BigCommerce.
Example screenshot of API Key and Enable Expedited Shipping Connection Options in the BC control panel:
To authorize the app to access the BigCommerce API on behalf of a store, install the app in the BigCommerce store:
- Log in to your BigCommerce store. If you don’t have one yet, sign up for a trial. Make sure to use the same email address that you used to register the app at https://devtools.bigcommerce.com/.
- Navigate to Apps > My Apps > My Draft Apps
- Click your app’s name
- Click the Install button, and confirm installation
At this point, BigCommerce creates an iframe in the control panel that sends the Auth request to the Auth Callback URL. The Install component at that route should present the signup form, then initiate signup with Cognito. If you encounter an error, try checking the following places for more information to help you debug:
- the browser’s JS console
- CloudWatch logs for the PreSignup Lambda function
- Consider adding support to run the standalone shell for react-dev-tools
The example app requires the user to close the app, then relaunch it. That’s because the successful signup request creates the user record in Cognito, but it does not grant the user the tokens it will need to access the app’s backend later. The app requires a Load request from BigCommerce to initiate the custom auth flow, and grant the tokens. The Load request is triggered when the user clicks the app’s icon in their BigCommerce control panel.
Once the carrier has been registered with BigCommerce and the app is installed, a new shipping method will be visible in the BigCommerce control panel when editing a shipping zone under from Store Setup > Shipping under Real Time Shipping Quotes:
Use the Connect button to enable the carrier, configure connection options, and test the rate request endpoint.
BigCommerce also provides APIs to manage shipping zones and configure shipping methods. This example app does not integrate with those APIs. Read more in the BigCommerce documentation.
- Log into the BigCommerce store
- Click Apps, then click the App’s icon
- Note: If the app’s icon is not present in the Apps menu, check to ensure the app is installed.
- At this point, the browser sends the Load Callback request to open the React client in an iframe. The React client should receive the request, and initiate the custom auth flow in Cognito.
- If you receive an error, check the CloudWatch logs for the Define Auth Challenge, Create Auth Challenge, and Verify Auth Challenge Response Lambda functions for more information.
- Confirm the UI is rendered
- Click the Get Store Information button
- At this point, the React client should use the API.get() method to invoke the app’s API with the identity and access tokens supplied by Cognito. If you receive an error from the API, check the CloudWatch logs for the bcApiClient and bcApiLambda functions.
- Confirm the React client receives the store’s information from the BigCommerce API
Once you are able to launch the UI in the BigCommerce control panel, you can add, remove, and edit the flat-rate shipping methods returned by the app.
- Log in to your store, and navigate to Apps > My Apps
- Click the Uninstall link for your app
- At this point, BigCommerce will send an uninstall request to the URL you supplied. You can use AWS console to check the user pool in Cognito and the table in DynamoDB to ensure the store’s user and BigCommerce Access Token have been deleted. If they aren’t deleted after uninstalling the app, check the CloudWatch logs for uninstall Lambda. If there are no log streams for the uninstall Lambda, check that the Invoke URL for the uninstall API matches the Uninstall Callback URL provided to BigCommerce.