Skip to main content

Actions

The ballerinax/sap.commerce.webservices package exposes the following clients:

ClientPurpose
ClientOCC v2 REST API: product catalog, carts, orders, customers, B2B procurement, stores, and tickets.

Client

OCC v2 REST API: product catalog, carts, orders, customers, B2B procurement, stores, and tickets.

Configuration

FieldTypeDefaultDescription
authhttp:BearerTokenConfig|OAuth2ClientCredentialsGrantConfigRequiredOAuth 2.0 client credentials config or bearer token for authentication.
httpVersionstring"2.0"HTTP protocol version.
timeoutdecimal60Request timeout in seconds.
retryConfighttp:RetryConfig()Retry configuration for failed requests.
secureSockethttp:SecureSocket()SSL/TLS configuration.
proxyhttp:ProxyConfig()Proxy server configuration.
circuitBreakerhttp:CircuitBreakerConfig()Circuit breaker configuration for fault tolerance.
compressionhttp:Compression()HTTP compression configuration.
cachehttp:CacheConfig()HTTP caching configuration.
poolConfighttp:PoolConfiguration()Connection pool configuration.

Initializing the client

import ballerinax/sap.commerce.webservices as sapCommerce;

configurable string clientId = ?;
configurable string clientSecret = ?;
configurable string tokenUrl = ?;
configurable string serviceUrl = ?;

sapCommerce:Client sapCommerceClient = check new (
{
auth: {
clientId: clientId,
clientSecret: clientSecret,
tokenUrl: tokenUrl
}
},
serviceUrl
);

Operations

Base sites & configuration

getBaseSites

Retrieves the list of available base sites.

Parameters:

NameTypeRequiredDescription
headersmap<string|string[]>NoOptional HTTP headers.
queriesGetBaseSitesQueriesNoQuery parameters including fields.

Returns: BaseSiteList|xml|error

Sample code:

sapCommerce:BaseSiteList|xml baseSites = check sapCommerceClient->getBaseSites({}, {fields: "DEFAULT"});

Sample response:

{"baseSites": [{"uid": "electronics", "name": "Electronics Site", "channel": "B2C", "defaultLanguage": {"isocode": "en"}}, {"uid": "powertools", "name": "Powertools Site", "channel": "B2B"}]}
getCountries

Retrieves a list of countries for the given base site.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
queriesGetCountriesQueriesNoQuery parameters including fields and type (SHIPPING or BILLING).

Returns: CountryList|xml|error

Sample code:

sapCommerce:CountryList|xml countries = check sapCommerceClient->getCountries("electronics", {}, {fields: "DEFAULT"});

Sample response:

{"countries": [{"isocode": "US", "name": "United States"}, {"isocode": "DE", "name": "Germany"}, {"isocode": "JP", "name": "Japan"}]}
getCurrencies

Retrieves a list of available currencies for the given base site.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
queriesGetCurrenciesQueriesNoQuery parameters including fields.

Returns: CurrencyList|xml|error

Sample code:

sapCommerce:CurrencyList|xml currencies = check sapCommerceClient->getCurrencies("electronics", {}, {fields: "DEFAULT"});

Sample response:

{"currencies": [{"isocode": "USD", "name": "US Dollar", "symbol": "$", "active": true}, {"isocode": "EUR", "name": "Euro", "symbol": "€", "active": true}]}

Product catalog

getCatalogs

Retrieves a list of catalogs for the given base site.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
queriesGetCatalogsQueriesNoQuery parameters including fields.

Returns: CatalogList|xml|error

Sample code:

sapCommerce:CatalogList|xml catalogs = check sapCommerceClient->getCatalogs("electronics", {}, {fields: "FULL"});

Sample response:

{"catalogs": [{"id": "electronicsProductCatalog", "name": "Electronics Product Catalog", "catalogVersions": [{"id": "Online", "active": true}, {"id": "Staged", "active": false}]}]}
getCatalogVersion

Retrieves information about a specific catalog version.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
catalogIdstringYesCatalog identifier.
catalogVersionIdstringYesCatalog version identifier (e.g., "Online").
queriesGetCatalogVersionQueriesNoQuery parameters including fields.

Returns: CatalogVersion|xml|error

Sample code:

sapCommerce:CatalogVersion|xml catalogVersion = check sapCommerceClient->getCatalogVersion(
"electronics", "electronicsProductCatalog", "Online", {}, {fields: "FULL"}
);

Sample response:

{"id": "Online", "lastModifiedTime": "2024-01-15T10:30:00Z", "categories": [{"id": "cameras", "name": "Cameras"}, {"id": "smartphones", "name": "Smartphones"}]}
getProductsByCategory

Retrieves a list of products for a category.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
categoryIdstringYesCategory identifier.
queriesGetProductsByCategoryQueriesNoQuery parameters including pageSize, currentPage, sort, query, and fields.

Returns: ProductSearchPage|xml|error

Sample code:

sapCommerce:ProductSearchPage|xml products = check sapCommerceClient->getProductsByCategory(
"electronics", "cameras", {}, {pageSize: 25, currentPage: 0, fields: "FULL", sort: "name-asc"}
);

Sample response:

{"pagination": {"pageSize": 25, "currentPage": 0, "totalResults": 42, "totalPages": 2}, "products": [{"code": "1382080", "name": "EOS 450D", "price": {"value": 574.88, "currencyIso": "USD"}, "stock": {"stockLevelStatus": "inStock"}}], "sorts": [{"code": "name-asc", "name": "Name (ascending)", "selected": true}]}

Products

getProducts

Retrieves a list of products with search and filtering.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
queriesGetProductsQueriesNoQuery parameters including query, pageSize, currentPage, sort, and fields.

Returns: ProductSearchPage|xml|error

Sample code:

sapCommerce:ProductSearchPage|xml searchResults = check sapCommerceClient->getProducts(
"electronics", {}, {query: "camera", pageSize: 10, fields: "DEFAULT"}
);

Sample response:

{"pagination": {"pageSize": 10, "currentPage": 0, "totalResults": 15}, "products": [{"code": "1382080", "name": "EOS 450D", "summary": "Digital SLR camera"}, {"code": "2934302", "name": "PowerShot A480", "summary": "Compact digital camera"}]}
getProduct

Retrieves details for a specific product.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
productCodestringYesProduct identifier.
queriesGetProductQueriesNoQuery parameters including fields.

Returns: Product|xml|error

Sample code:

sapCommerce:Product|xml product = check sapCommerceClient->getProduct(
"electronics", "1382080", {}, {fields: "FULL"}
);

Sample response:

{"code": "1382080", "name": "EOS 450D", "description": "12.2 megapixel CMOS sensor", "price": {"value": 574.88, "currencyIso": "USD", "formattedValue": "$574.88"}, "stock": {"stockLevel": 241, "stockLevelStatus": "inStock"}, "averageRating": 4.5, "numberOfReviews": 12, "purchasable": true, "categories": [{"code": "cameras", "name": "Cameras"}]}
getProductReviews

Retrieves the reviews of a product.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
productCodestringYesProduct identifier.
queriesGetProductReviewsQueriesNoQuery parameters including fields and maxCount.

Returns: ReviewList|xml|error

Sample code:

sapCommerce:ReviewList|xml reviews = check sapCommerceClient->getProductReviews(
"electronics", "1382080", {}, {fields: "FULL"}
);

Sample response:

{"reviews": [{"id": "8796093055001", "headline": "Great camera", "comment": "Excellent image quality for the price.", "rating": 5.0, "alias": "PhotoFan", "date": "2024-03-10T14:22:00Z"}]}
createProductReview

Creates a customer review for a product.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
productCodestringYesProduct identifier.
payloadReviewYesReview data including headline, comment, rating, and alias.
queriesCreateProductReviewQueriesNoQuery parameters including fields.

Returns: Review|xml|error

Sample code:

sapCommerce:Review|xml review = check sapCommerceClient->createProductReview(
"electronics", "1382080",
{headline: "Great camera", comment: "Excellent image quality.", rating: 5.0, alias: "PhotoFan"},
{}, {fields: "DEFAULT"}
);

Sample response:

{"id": "8796093055002", "headline": "Great camera", "comment": "Excellent image quality.", "rating": 5.0, "alias": "PhotoFan", "date": "2024-06-15T09:30:00Z"}

Customer management

createUser

Registers a new customer.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
payloadUserSignUpYesUser registration data including uid, firstName, lastName, and password.
queriesCreateUserQueriesNoQuery parameters including fields.

Returns: User|xml|error

Sample code:

sapCommerce:User|xml user = check sapCommerceClient->createUser(
"electronics",
{uid: "[email protected]", firstName: "John", lastName: "Doe", password: "SecurePass123!"},
{}, {fields: "DEFAULT"}
);

Sample response:

{"uid": "[email protected]", "name": "John Doe", "firstName": "John", "lastName": "Doe", "currency": {"isocode": "USD"}, "language": {"isocode": "en"}}
getUser

Retrieves the customer profile.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
userIdstringYesUser identifier or 'current' for the authenticated user.
queriesGetUserQueriesNoQuery parameters including fields.

Returns: User|xml|error

Sample code:

sapCommerce:User|xml user = check sapCommerceClient->getUser(
"electronics", "[email protected]", {}, {fields: "FULL"}
);

Sample response:

{"uid": "[email protected]", "name": "John Doe", "firstName": "John", "lastName": "Doe", "displayUid": "[email protected]", "currency": {"isocode": "USD"}, "language": {"isocode": "en"}}
getAddresses

Retrieves the addresses of a customer.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
userIdstringYesUser identifier.
queriesGetAddressesQueriesNoQuery parameters including fields.

Returns: AddressList|xml|error

Sample code:

sapCommerce:AddressList|xml addresses = check sapCommerceClient->getAddresses(
"electronics", "[email protected]", {}, {fields: "DEFAULT"}
);

Sample response:

{"addresses": [{"id": "8796093710359", "firstName": "John", "lastName": "Doe", "line1": "123 Main St", "town": "New York", "postalCode": "10001", "country": {"isocode": "US"}, "defaultAddress": true}]}
createAddress

Creates a new address for a customer.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
userIdstringYesUser identifier.
payloadAddressYesAddress data including firstName, lastName, line1, town, postalCode, and country.
queriesCreateAddressQueriesNoQuery parameters including fields.

Returns: Address|xml|error

Sample code:

sapCommerce:Address|xml address = check sapCommerceClient->createAddress(
"electronics", "[email protected]",
{
firstName: "John",
lastName: "Doe",
line1: "123 Main St",
town: "New York",
postalCode: "10001",
country: {isocode: "US"}
},
{}, {fields: "DEFAULT"}
);

Sample response:

{"id": "8796093710359", "firstName": "John", "lastName": "Doe", "line1": "123 Main St", "town": "New York", "postalCode": "10001", "country": {"isocode": "US"}, "defaultAddress": false}

Cart management

createCart

Creates or restores a cart for a user.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
userIdstringYesUser identifier or 'current' / 'anonymous'.
queriesCreateCartQueriesNoQuery parameters including fields, oldCartId, and toMergeCartGuid.

Returns: Cart|xml|error

Sample code:

sapCommerce:Cart|xml cart = check sapCommerceClient->createCart(
"electronics", "[email protected]", {}, {fields: "DEFAULT"}
);

Sample response:

{"code": "00001001", "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "totalItems": 0, "totalPrice": {"value": 0.0, "currencyIso": "USD", "formattedValue": "$0.00"}}
getCarts

Retrieves all carts of a customer.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
userIdstringYesUser identifier.
queriesGetCartsQueriesNoQuery parameters including fields, savedCartsOnly, currentPage, and pageSize.

Returns: CartList|xml|error

Sample code:

sapCommerce:CartList|xml carts = check sapCommerceClient->getCarts(
"electronics", "[email protected]", {}, {fields: "DEFAULT"}
);

Sample response:

{"carts": [{"code": "00001001", "totalItems": 2, "totalPrice": {"value": 1149.76, "currencyIso": "USD", "formattedValue": "$1,149.76"}}]}
getCart

Retrieves a specific cart.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
cartIdstringYesCart identifier or 'current' for the last modified cart.
userIdstringYesUser identifier.
queriesGetCartQueriesNoQuery parameters including fields.

Returns: Cart|xml|error

Sample code:

sapCommerce:Cart|xml cart = check sapCommerceClient->getCart(
"electronics", "00001001", "[email protected]", {}, {fields: "FULL"}
);

Sample response:

{"code": "00001001", "totalItems": 2, "totalPrice": {"value": 1149.76, "currencyIso": "USD"}, "entries": [{"entryNumber": 0, "product": {"code": "1382080", "name": "EOS 450D"}, "quantity": 2, "totalPrice": {"value": 1149.76}}], "deliveryMode": {"code": "standard-gross"}}

Orders

placeOrder

Creates an order from the current cart.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
userIdstringYesUser identifier.
queriesPlaceOrderQueriesNoQuery parameters including cartId, termsChecked, securityCode, and fields.

Returns: Order|xml|error

Sample code:

sapCommerce:Order|xml placedOrder = check sapCommerceClient->placeOrder(
"electronics", "[email protected]",
{}, {cartId: "00001001", termsChecked: true, fields: "FULL"}
);

Sample response:

{"code": "00002001", "status": "CREATED", "statusDisplay": "created", "created": "2024-06-15T14:30:00Z", "totalPrice": {"value": 1149.76, "currencyIso": "USD", "formattedValue": "$1,149.76"}, "entries": [{"entryNumber": 0, "product": {"code": "1382080", "name": "EOS 450D"}, "quantity": 2}]}
getOrders

Retrieves the order history for a customer.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
userIdstringYesUser identifier.
queriesGetOrdersQueriesNoQuery parameters including pageSize, currentPage, sort, statuses, and fields.

Returns: OrderHistoryList|xml|error

Sample code:

sapCommerce:OrderHistoryList|xml orders = check sapCommerceClient->getOrders(
"electronics", "[email protected]", {}, {pageSize: 10, fields: "DEFAULT"}
);

Sample response:

{"orders": [{"code": "00002001", "status": "COMPLETED", "statusDisplay": "completed", "placed": "2024-06-15T14:30:00Z", "total": {"value": 1149.76, "currencyIso": "USD"}}], "pagination": {"pageSize": 10, "currentPage": 0, "totalResults": 1}}
getOrder

Retrieves a specific order by code or GUID.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
codestringYesOrder GUID or order code.
queriesGetOrderQueriesNoQuery parameters including fields.

Returns: Order|xml|error

Sample code:

sapCommerce:Order|xml retrievedOrder = check sapCommerceClient->getOrder(
"electronics", "00002001", {}, {fields: "FULL"}
);

Sample response:

{"code": "00002001", "status": "COMPLETED", "statusDisplay": "completed", "created": "2024-06-15T14:30:00Z", "totalPrice": {"value": 1149.76, "currencyIso": "USD"}, "deliveryAddress": {"firstName": "John", "lastName": "Doe", "line1": "123 Main St", "town": "New York"}, "entries": [{"entryNumber": 0, "product": {"code": "1382080", "name": "EOS 450D"}, "quantity": 2}]}

Store locator

getStoreLocations

Retrieves store locations with optional geo-search.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
queriesGetStoreLocationsQueriesNoQuery parameters including query, latitude, longitude, radius, pageSize, and fields.

Returns: StoreFinderSearchPage|xml|error

Sample code:

sapCommerce:StoreFinderSearchPage|xml stores = check sapCommerceClient->getStoreLocations(
"electronics", {},
{query: "New York", latitude: 40.7128, longitude: -74.006, radius: 50000.0, pageSize: 10, fields: "FULL"}
);

Sample response:

{"stores": [{"name": "Manhattan Store", "displayName": "Manhattan Electronics", "address": {"line1": "456 Broadway", "town": "New York", "postalCode": "10013", "country": {"isocode": "US"}}, "geoPoint": {"latitude": 40.7209, "longitude": -73.9984}}], "pagination": {"pageSize": 10, "totalResults": 3}}
getStoreLocation

Retrieves details for a specific store location.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
storeIdstringYesStore identifier (store name).
queriesGetStoreLocationQueriesNoQuery parameters including fields.

Returns: PointOfService|xml|error

Sample code:

sapCommerce:PointOfService|xml store = check sapCommerceClient->getStoreLocation(
"electronics", "Manhattan Store", {}, {fields: "FULL"}
);

Sample response:

{"name": "Manhattan Store", "displayName": "Manhattan Electronics", "address": {"line1": "456 Broadway", "town": "New York", "postalCode": "10013", "country": {"isocode": "US"}, "phone": "+1-212-555-0100"}, "geoPoint": {"latitude": 40.7209, "longitude": -73.9984}, "openingHours": {"weekDayOpeningList": [{"weekDay": "Mon", "openingTime": {"formattedHour": "09:00 AM"}, "closingTime": {"formattedHour": "09:00 PM"}}]}}

Support tickets

getTicketCategories

Retrieves the available ticket categories.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
queriesGetTicketCategoriesQueriesNoQuery parameters including fields.

Returns: TicketCategoryList|error

Sample code:

sapCommerce:TicketCategoryList categories = check sapCommerceClient->getTicketCategories(
"electronics", {}, {fields: "DEFAULT"}
);

Sample response:

{"ticketCategories": [{"id": "COMPLAINT", "name": "Product Complaint"}, {"id": "RETURNS", "name": "Product Returns"}, {"id": "ENQUIRY", "name": "General Enquiry"}]}
createTicket

Creates a new support ticket for a customer.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
userIdstringYesUser identifier.
payloadTicketStarterYesTicket data including subject, message, ticketCategory, and associatedTo.
queriesCreateTicketQueriesNoQuery parameters including fields.

Returns: Ticket|error

Sample code:

sapCommerce:Ticket ticket = check sapCommerceClient->createTicket(
"electronics", "[email protected]",
{
subject: "Defective smartphone screen",
message: "Screen started flickering after 3 days of normal use.",
ticketCategory: {id: "COMPLAINT", name: "Product Complaint"},
associatedTo: {code: "00001234", 'type: "Order"}
},
{}, {fields: "DEFAULT"}
);

Sample response:

{"id": "TKT-000042", "subject": "Defective smartphone screen", "status": {"id": "OPEN", "name": "Open"}, "createdAt": "2024-06-15T10:00:00Z", "ticketCategory": {"id": "COMPLAINT", "name": "Product Complaint"}}
createTicketEvent

Adds a follow-up event or status update to an existing ticket.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
ticketIdstringYesTicket identifier.
userIdstringYesUser identifier.
payloadTicketEventYesEvent data including message, addedByAgent, and optional toStatus.
queriesCreateTicketEventQueriesNoQuery parameters including fields.

Returns: TicketEvent|error

Sample code:

sapCommerce:TicketEvent event = check sapCommerceClient->createTicketEvent(
"electronics", "TKT-000042", "[email protected]",
{
message: "Escalating to technical team for warranty replacement.",
addedByAgent: true,
author: "[email protected]"
},
{}, {fields: "DEFAULT"}
);

Sample response:

{"code": "EVT-001", "message": "Escalating to technical team for warranty replacement.", "author": "[email protected]", "addedByAgent": true, "createdAt": "2024-06-15T11:30:00Z"}

B2B procurement

createCostCenter

Creates a new cost center for B2B organizational budgeting.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
payloadB2BCostCenterYesCost center data including code, name, activeFlag, and currency.
queriesCreateCostCenterQueriesNoQuery parameters including fields.

Returns: B2BCostCenter|error

Sample code:

sapCommerce:B2BCostCenter costCenter = check sapCommerceClient->createCostCenter(
"powertools",
{
code: "CC-MKTG-2024",
name: "Marketing Department Cost Center 2024",
activeFlag: true,
currency: {isocode: "USD", name: "US Dollar", symbol: "$", active: true}
},
{}, {fields: "FULL"}
);

Sample response:

{"code": "CC-MKTG-2024", "name": "Marketing Department Cost Center 2024", "activeFlag": true, "currency": {"isocode": "USD", "name": "US Dollar", "symbol": "$"}}
doAddBudgetToCostCenter

Associates a budget with a cost center.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
costCenterCodestringYesCost center code to which the budget will be added.
queriesDoAddBudgetToCostCenterQueriesNoQuery parameters including budgetCode and fields.

Returns: B2BSelectionData|error

Sample code:

sapCommerce:B2BSelectionData budgetAssignment = check sapCommerceClient->doAddBudgetToCostCenter(
"powertools", "CC-MKTG-2024",
{}, {budgetCode: "BUDGET-MKTG-2024", fields: "DEFAULT"}
);

Sample response:

{"id": "BUDGET-MKTG-2024", "active": true, "selected": true, "normalizedCode": "budget-mktg-2024"}
createQuote

Creates a quote request from an existing cart.

Parameters:

NameTypeRequiredDescription
baseSiteIdstringYesBase site identifier.
userIdstringYesUser identifier.
payloadQuoteStarterYesQuote starter data including cartId.
queriesCreateQuoteQueriesNoQuery parameters including fields.

Returns: Quote|error

Sample code:

sapCommerce:Quote quote = check sapCommerceClient->createQuote(
"powertools", "[email protected]",
{cartId: "00001234"},
{}, {fields: "FULL"}
);

Sample response:

{"code": "QT-000001", "state": "BUYER_DRAFT", "version": 1, "name": "Quote QT-000001", "creationTime": "2024-06-15T09:00:00Z", "totalPrice": {"value": 2450.00, "currencyIso": "USD"}}