Purpose
The purpose of this document is to list the high-level API endpoints required for headless commerce(B2C). This will helps in finalizing API design.
API Endpoints
Authentication
| Sr No. | API Endpoint | Description | Tasks | Status | Phase |
|---|---|---|---|---|---|
| 1 | POST /guest-token | This API will return a token for a guest account. | Planning | I | |
| 2 | POST /customer-token | This API will return a token for the registered user. | Planning | I | |
| 3 | POST /refresh-token | In case we need to update the token. As JWT token ideally contains a certain expiry time. So if the user is active then instead of getting him to log out, this API can generate a new token from the existing token. | Planning | I |
Customer
| Sr No. | API Endpoint | Description | Tasks | Status | Phase |
|---|---|---|---|---|---|
| Customer Profile | |||||
| 1 | POST /customers | To register the customer. | Planning | I | |
| 2 | GET /customers/password-hint | To get the password hint. | Planning | I | |
| 3 | POST /customers/reset-password | To get the reset password link on the registered email. | Planning | I | |
| 4 | POST /customers/{customerPartyId}/change-password | To change the password. | Planning | I | |
| 5 | POST /customers/{customerPartyId}/profile | To get the complete profile of a customer, personal information, addresses, emails, phones, etc. There should be one filter to bring specific information like only personal information, only addresses, etc. | Planning | I | |
| 6 | PUT /customers/{customerPartyId} | To update the customer's personal information. | Planning | I | |
| 7 | POST /customers/{customerPartyId}/addresses | To create the postal address. | Planning | I | |
| 8 | PUT /customers/{customerPartyId}/addresses/{contactMechId} | To update the postal address and to mark the default address. | Planning | I | |
| 9 | DELETE /customers/{customerPartyId}/addresses/{contactMechId} | To delete/expire the postal address. | Planning | I | |
| 10 | POST /customers/{customerPartyId}/phones | To create a telecom number. | Planning | I | |
| 11 | PUT /customers/{customerPartyId}/phones/{contactMechId} | To update a telecom number. | Planning | I | |
| 12 | DELETE /customers/{customerPartyId}/phones/{contactMechId} | To delete a telecom number | Planning | I | |
| 13 | POST /customers/{customerPartyId}/emails | To create an email address. | Planning | I | |
| 14 | PUT /customers/{customerPartyId}/emails/{contactMechId} | To update an email address. | Planning | I | |
| 15 | DELETE /customers/{customerPartyId}/emails/{contactMechId} | To remove an email address. | Planning | I | |
| 16 | POST /customers/{customerPartyId}/contact-information | To add the other contact information like electronic address, Internet IP address, Internet Domain Name, Web Url, LDAP address, File server, etc. | Planning | I | |
| 17 | PUT /customers/{customerPartyId}/contact-information/{contactMechId} | To update the other contact information like electronic address, Internet IP address, Internet Domain Name, Web Url, LDAP address, File server, etc. | Planning | I | |
| 18 | DELETE /customers/{customerPartyId}/contact-information/{contactMechId} | To remove the other contact information like electronic address, Internet IP address, Internet Domain Name, Web Url, LDAP address, File server, etc. | Planning | I | |
| 19 | POST /customers/{customerPartyId}/sendEmail | To send the mail from the profile page to the added email address. | Planning | I | |
| 20 | POST /customers/{customerPartyId}/credit-cards | To create a credit card. | Planning | I | |
| 21 | PUT /customers/{customerPartyId}/credit-cards/{paymentMethodId} | To update the credit card detail and to mark it as default. | Planning | I | |
| 22 | DELETE /customers/{customerPartyId}/credit-cards/{paymentMethodId} | To remove a credit card. | Planning | I | |
| 23 | POST /customers/{customerPartyId}/gift-cards | To create a gift card. | Planning | I | |
| 24 | PUT /customers/{customerPartyId}/gift-cards/{paymentMethodId} | To update the gift card detail and to mark it as default. | Planning | I | |
| 25 | DELETE /customers/{customerPartyId}/gift-cards/{paymentMethodId} | To remove the gift card. | Planning | I | |
| 26 | POST /customers/{customerPartyId}/eft-accounts | To create an EFT account. | Planning | I | |
| 27 | PUT /customers/{customerPartyId}/eft-accounts/{paymentMethodId} | To update the EFT account detail and to mark it as default. | Planning | I | |
| 28 | DELETE /customers/{customerPartyId}/eft-accounts/{paymentMethodId} | To remove the EFT account. | Planning | I | |
| 29 | POST /customers/{customerPartyId}/shipment-methods/{shipmentMethodId} | To mark the default shipping method if there is a default shipping address. | Planning | I | |
| 30 | POST /customers/{customerPartyId}/contact-list/{contactListId}/subscription | To subscribe to the contact list. | Planning | I | |
| 31 | PUT /customers/{customerPartyId}/contact-list/{contactListId/subscription | To unsubscribe the contact list. | Planning | I | |
| Order History & Return | |||||
| 1 | GET /customers/{customerPartyId}/orders | To fetch all the orders of a customer. | Planning | I | |
| 2 | GET /customers/{customerPartyId}/orders/{orderId} | To fetch the order detail. | Planning | I | |
| 3 | PUT /customers/{customerPartyId}/orders/{orderId} | To update the order. Right now the support to cancel an item(partially or fully) is there. That should be handled in this API. | Planning | I | |
| 4 | GET /customers/{customerPartyId}/orders/{orderId}/order-pdf | To get the order pdf. | Planning | I | |
| 5 | GET /customers/{customerPartyId}/orders/{orderId}/invoice-pdf | To get the invoice pdf. | Planning | I | |
| 6 | POST /customers/{customerPartyId}/returns | To create a return. | Planning | I | |
Catalog
| Sr No. | API Endpoint | Description | Tasks | Status | Phase |
|---|---|---|---|---|---|
| Catalog | |||||
| 1 | GET /catalogs | To get the list of catalogs. | Planning | I | |
| 2 | GET /catalogs/{catalogId} | To get the feature categories, feature products, category hierarchy in a single call. | Planning | I | |
| 3 | GET /catalogs/{catalogId}/feature-categories | To get the feature categories of a catalog. | Planning | I | |
| 4 | GET /catalogs/{catalogId}/feature-products | To get the feature products of a catalog. | Planning | I | |
| 5 | GET /catalogs/{catalogId}/category-hierarchy | To get the category hierarchy of a catalog. | Planning | I | |
| 6 | GET /products | This API will have support for the search string and other additional filters. This API will also bring the products of a selected category if provided. | Planning | I | |
| 7 | GET /products/{productId} | To get the product detail. | Planning | I | |
| 8 | POST /products/{productId}/reviews | To add a review of a product. | Planning | I | |
| 9 | GET /products/{productId}/reviews | To get the reviews of a product. | Planning | I | |
| 10 | GET /products/{productId}/associated-products | To get the list of cross-sell/upsell products. | Planning | I | |
| 11 | POST /products/{productId}/product-tags | To add a tag for a product. | Planning | I | |
| 12 | GET /products/{productId}/product-tags | To get all the tags of a product. | Planning | I | |
| 13 | GET /products/product-tags | All the product tags for the tag cloud. | Planning | I | |
| 14 | GET /offers | To list the special offers | Planning | I | |
| 15 | GET /offers/{promotionId} | To get the complete detail of a particular offer | Planning | I | |
| 16 | POST /sendMail | For Tell a Friend functionality | Planning | I | |
| 17 | POST /products/compare-list | To create a compare list and to add a product to it. | Planning | I | |
| 18 | GET /products/compare-list | To get the list of added products with detail for the comparison view. | Planning | I | |
| 19 | DELETE /products/compare-list/{productId} | To remove a product from the compare list. | Planning | I | |
Shopping List and Quotes
| Sr No. | API Endpoint | Description | Tasks | Status | Phase |
|---|---|---|---|---|---|
| Shopping List | |||||
| 1 | POST /shopping-lists | To create a new shopping list. | Planning | I | |
| 2 | GET /shopping-lists | To get the list of shopping lists. | Planning | I | |
| 3 | GET /shopping-lists/{shoppingListId} | To get the detail of a shopping list. This will also bring the list of available interval/frequency data for setting the recurrence detail using the update shopping list API. | Planning | I | |
| 4 | PUT /shopping-lists/{shoppingListId} | To update the shopping list detail. Recurrence info can also be set from this API. | Planning | I | |
| 5 | POST /shopping-lists/{shoppingListId}/items | Add an item to the shopping list. | Planning | I | |
| 6 | GET /shopping-lists/{shoppingListId}/items | Get the list of items on a shopping list. | Planning | I | |
| 7 | PUT /shopping-lists/{shoppingListId}/items/{itemId} | Update the particular item on the shopping list. | Planning | I | |
| 8 | DELETE /shopping-lists/{shoppingListId}/items/{itemId} | Remove the particular item from the shopping list. | Planning | I | |
| Quote | |||||
| 1 | POST /quote-requests | Quotes Request can be created from the shopping list and from the cart. This API will create a quote request. | Planning | I | |
| 2 | GET /quote-requests | To get the list of quote requests(request history). | Planning | I | |
| 3 | GET /quote-requests/{requestId} | To get the detail of a quote request. | Planning | I | |
| 4 | GET /quotes | To get the list of quotes. | Planning | I | |
| 5 | GET /quotes/{quoteId} | To get the detail of a quote. | Planning | I | |
| 6 | POST /order-quotes | To create an order from the quote. | Planning | I | |
Shopping Cart & Checkout
Note: The below API endpoints are written considering the Object-Oriented implementation of Shopping Cart. We need to identify the best way to store the shopping cart object as the user session won't be in the picture here. One way to introduce a new table to keep the cart object with a unique cart ID. For better performance cache can also be used efficiently. The cart object should have the last updated timestamp so that a clear policy to remove the abandoned cart can be imposed.
| Sr No. | API Endpoint | Description | Tasks | Status | Phase |
|---|---|---|---|---|---|
| Shopping Cart | |||||
| 1 | POST /carts | Planning | I | ||
| 2 | GET /carts/{cartReference} | Planning | I | ||
| 3 | DELETE /carts/{cartReference} | Planning | I | ||
| 4 | POST /carts/{cartReference}/items | For adding products and other order adjustments like shipping charges, tax, etc. | Planning | I | |
| 5 | GET /carts/{cartReference}/items | Planning | I | ||
| 6 | PUT /carts/{cartReference}/items/{itemSeqId} | Planning | I | ||
| 7 | DELETE /carts/{cartReference}/items/{itemSeqId} | Planning | I | ||
| 8 | POST /carts/{cartReference}/promotions | To apply the promo code on the cart. | Planning | I | |
| 9 | DELETE /carts/{cartReference}/promotions/{itemSeqId} | To remove an applied promotion. | Planning | I | |
| 10 | POST /carts/{cartReference}/items/shopping-list/{shoppingListId} | This will add all the items of a given shopping list to the cart. | Planning | I | |
| 11 | POST /carts/{cartReference}/items/order/{orderId} | This will add all the items of a given past order to the cart. | Planning | I | |
| Checkout | |||||
| 1 | POST /carts/{cartReference}/ship-groups | To create a new ship group in case of split shipment. | Planning | I | |
| 2 | GET /carts/{cartReference}/ship-groups | To get the ship groups with items. | Planning | I | |
| 3 | POST /carts/{cartReference}/ship-groups/{shipGroupSeqId}/shipping-address | To add the shipping address. | Planning | I | |
| 4 | POST /carts/{cartReference}/ship-groups/{shipGroupSeqId}/items | To move items from one ship group to another in case of split shipment. | Planning | I | |
| 5 | POST /carts/{cartReference}/ship-groups/{shipGroupSeqId}/shipping-instructions | To add special instructions, gift message in case of a gift, split preferences(ship all items together or ship items when available) | Planning | I | |
| 6 | PUT /carts/{cartReference}/ship-groups/{shipGroupSeqId}/shipping-instructions | To update special instructions, gift message in case of a gift, split preferences(ship all items together or ship items when available) | Planning | I | |
| 7 | GET /shipping-methods} | To get the shipping methods. | Planning | I | |
| 8 | POST /carts/{cartReference}/ship-groups/{shipGroupSeqId}/shipping-method | To add/update the shipping method. | Planning | I | |
| 9 | GET /payment-options | To get the list of supported payment options. | Planning | I | |
| 10 | POST /carts/{cartReference}/payment-methods | To add a payment method. The combination of the gift card and other payment methods are supported as of now. | Planning | I | |
| 11 | POST /checkout | To place the order. | Planning | I | |
| Anonymous Checkout | |||||
| 1 | POST /carts/{cartReference}/guest/personal-information | Set the anonymous user's detail for the order. Name, phone, email, etc. | Planning | I | |
| 2 | PUT /carts/{cartReference}/guest/personal-information | Planning | I | ||
| 3 | POST /carts/{cartReference}/guest/shipping-address | Planning | I | ||
| 4 | PUT /carts/{cartReference}/guest/shipping-address | Planning | I | ||
| 5 | POST /carts/{cartReference}/guest/payment-informaion | Planning | I | ||
| 6 | PUT /carts/{cartReference}/guest/payment-informaion | Planning | I | ||