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 | GET POST /getGuestTokenguest-token | This API will return a token for a guest account. |
| Planning | I |
2 | POST /getCustomerTokencustomer-token | This API will return a token for the registered user. |
| Planning | I |
3 | POST /refreshTokenrefresh-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/PRs | Status | Phase |
---|
1 | POST /customers | To register the customer. |
Planning/password-hint 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 | GET /customers/{customerPartyId} | To get the full data of the customer profile. | 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 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}/ |
emailsTo 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 | 16contactinformation 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}/ |
contactinformationaddresses/{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}/ |
creditcardspaymentMethodId 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}/ |
giftcards 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} remove the gift card.Planning | I | 26 | POST /customers/{customerPartyId}/eft-accounts | To create an EFT account. | Planning | I | 27eftaccountsmethods/{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}/ |
shipmentshipmentMethodId 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 | 32ordersorder-history | To fetch all the orders of a customer. |
Planning | I | 33 | GET /customers/{customerPartyId}/orders/{orderId} | To fetch the order detail. | Planning | I | 34 | 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 | 35 | GET /customers/{customerPartyId}/orders/{orderId}/order-pdf | To get the order pdf. | Planning | I | 36 | GET /customers/{customerPartyId}/orders/{orderId}/invoice-pdf | To get the invoice pdf. | Planning | I | 37 | POST /customers/{customerPartyId}/returns | To create a return. | Planning | I |
Catalog
Sr No. | API Endpoint | Description | Tasks | Status | Phase |
---|
1 | GET / |
catalogsTo get the list of catalogs. | Planning | I | 2 | GET /catalogs/{catalogId} feature categories, feature products, in a single call3GET /catalogs/{catalogId}/feature-categories | To get the feature categories of a catalog. | Planning | I | GET /categories/{categoryId} | This will fetch all the products of a category |
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 catalog63 | 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 |
74 | GET /products/{productId} | To get the product detail. |
| Planning | I |
85 | POST /products/{productId}/reviews | To add a review of a product. |
| Planning | I |
9 /products{productId}/reviewsTo 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 it18 | 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
Wishlist
Sr No. | API Endpoint | Description | Tasks | Status | Phase |
---|
1 | POST / | shopping-listsTo 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 listcustomers/{customerPartyId}/wishlist | To Create a wishlist. |
| Planning |
|
1 | PUT /customers/{customerPartyId}/wishlist/{wishlistId} | To add a product to the wishlist. |
| Planning | I |
62GET | DELETE / | shopping-listscustomers/{ | shoppingListIdcustomerPartyId}/ | itemsGet 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 listwishlist/{wishlistId}/{productId} | To remove a product from the wishlist. |
| Planning | I |
3 | GET /customers/{customerPartyId}/wishlist/{wishlistId} | To get the wishlist | 9 | 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 | 10 | GET /quote-requests | To get the list of quote requests(request history). | Planning | I | 11 | GET /quote-requests/{requestId} | To get the detail of a quote request. | Planning | I | 12 | GET /quotes | To get the list of quotes. | Planning | I | 13 | GET /quotes/{quoteId} | To get the detail of a quote. | Planning | I | 14 | POST /order-quotes | To create an order from the quote. |
| Planning | I |
...
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 |
---|
1 | POST / | cartsorders | To Create an order with all the necessary detail (items, shipping address, payment information, etc.) |
| Planning | I |
2 | PATCH /orders/{orderId}/statuses/CANCEL | To cancel an order. |
| Planning | I |
3 | PATCH /orders/{orderId}/items/statuses/CANCEL | To Cancel order items. |
| Planning | I | 2 | GET /carts/{cartReference} | 3 | DELETE /carts/{cartReference} | 4 | POST /carts/{cartReference}/items | For adding products and other order adjustments like shipping charges, tax, etc. | 5 | GET /carts/{cartReference}/items | 6 | PUT /carts/{cartReference}/items/{itemSeqId} | 7 | DELETE /carts/{cartReference}/items/{itemSeqId} | 8 | POST /carts/{cartReference}/promotions | To apply the promo code on the cart. | 9 | DELETE /carts/{cartReference}/promotions/{itemSeqId} | To remove an applied promotion. | 10 | POST /carts/{cartReference}/items/shopping-list/{shoppingListId} | This will add all the items of a given shopping list to the cart. | 11 | POST /carts/{cartReference}/items/order/{orderId} | This will add all the items of a given past order to the cart. | 12 | POST /carts/{cartReference}/ship-groups | To create a new ship group in case of split shipment. | 13 | GET /carts/{cartReference}/ship-groups | To get the ship groups with items. | 14 | POST /carts/{cartReference}/ship-groups/{shipGroupSeqId}/shipping-address/{contactMechId} | To add the shipping address. | 15 | POST /carts/{cartReference}/ship-groups/{shipGroupSeqId}/items | To move items from one ship group to another in case of split shipment. | 16 | 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) | 17 | 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) | 18 | GET /shipping-methods} | To get the shipping methods. | 19 | POST /carts/{cartReference}/ship-groups/{shipGroupSeqId}/shipping-method | To add/update the shipping method. | 20 | GET /payment-options | To get the list of supported payment options. | 21 | 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. | 22 | POST /checkout | To place the order. |