Ecommerce (0.8.0)

Combines one or more split orders belonging to the same parent order.

The selected split orders are merged back into the parent split structure. After combining, the split order sequence is recalculated so that the remaining split orders use consecutive split numbers.

Features

• Combine multiple split orders.
• Combine split orders belonging to the same parent order.
• Reduce the number of split orders after a combination.
• Recalculate split order IDs after combining.
• Combine all split orders belonging to a parent order.
• Specify the processing status for the resulting order.

Split Order IDs

The order_ids path parameter contains the IDs of the split orders to combine.

Multiple order IDs must be supplied as comma-separated values.

Example:

/aalam/ecomm/order/NZRL6451-1,NZRL6451-2/combine

Split Sequence

Split orders are identified using the parent order number followed by a sequential suffix.

For example:

• NZRL6451-1
• NZRL6451-2
• NZRL6451-3
• NZRL6451-4

When split orders are combined, the remaining split orders are renumbered to maintain a continuous sequence.

For example, combining NZRL6451-1 and NZRL6451-2 results in the remaining split orders being represented using the reduced split sequence.

Parent Order

All split orders being combined must belong to the same parent order.

Split orders from different parent orders cannot be combined.

Combining All Splits

All split orders belonging to the same parent order can be combined.

When all splits are combined, the parent order becomes the resulting order and the split structure is removed.

Status

The status query parameter specifies the processing status to use when combining the orders.

Status values are configured by the administrator and are not restricted to a predefined enum.

Notes

• order_ids must contain valid split order IDs.
• At least one valid order ID must be supplied.
• The supplied split orders must belong to the same parent order.
• The specified split orders are combined into the parent order's split structure.
• The remaining split orders are renumbered after the combination.
• The number of split orders decreases after a successful combination.
• The parent order ID remains unchanged.
• All split orders belonging to the parent order can be combined.

Permissions

Order/manage is needed

Downloads the invoice PDF for one or more orders.

The order IDs are provided as comma-separated values in the order_ids path parameter.

Features

• Download an invoice PDF for a single order.
• Download invoice PDFs for multiple orders.
• Accept multiple order IDs as comma-separated values.
• Generate the invoice document for the specified orders.

Order IDs

The order_ids path parameter accepts one or more order IDs separated by commas.

Example:

/aalam/ecomm/order/ZHKI2831,CILC1923/invoice

Notes

• Each supplied order ID must identify a valid order.
• The generated response is an invoice PDF file.
• Multiple order IDs can be supplied in a single request.
• The endpoint is intended for downloading invoice documents rather than returning JSON order data.

Permissions

Any of the following permissions are needed

• Orders/access
• Orders/manage
• Orders/edit
• Orders/process

Downloads the shipping label for one or more orders.

The order IDs are provided as comma-separated values in the order_ids path parameter.

Features

• Download a shipping label for a single order.
• Download shipping labels for multiple orders.
• Accept multiple order IDs as comma-separated values.
• Generate the shipping label document for the specified orders.

Order IDs

The order_ids path parameter accepts one or more order IDs separated by commas.

Example:

/aalam/ecomm/order/CILC1923/shipping_label

Multiple orders can be requested using comma-separated order IDs:

/aalam/ecomm/order/ZHKI2831,CILC1923/shipping_label

Notes

• Each supplied order ID must identify a valid order.
• The response contains the generated shipping label document.
• Multiple order IDs can be supplied in a single request.
• The endpoint is intended for downloading shipping label documents rather than returning JSON order data.

Permissions

Any of the following permissions are needed

• Orders/access
• Orders/manage
• Orders/edit
• Orders/process

Retrieves detailed information for a specific order.

The response includes the current order state, processing history, invoice details, order items, tags, causes, and related split and return orders.

Features

• Retrieve details of a specific order.
• Retrieve the current order status and processing state.
• Retrieve the complete order status history.
• Retrieve invoice and settlement details.
• Retrieve order items.
• Select specific item fields using item_fields.
• Retrieve order tags and processing causes.
• Retrieve related split orders.
• Retrieve related return orders.

Item Fields

The item_fields parameter can be used to control which item fields are returned in the invoice item details.

Multiple fields can be supplied as a comma-separated list.

Example:

item_fields=id,code,name,type,type_id,uom

Notes

• The order_id must be a valid order number.
• If the specified order does not exist, a 404 Not Found response is returned.
• The item_fields parameter applies to item details returned inside the invoice.
• Order status values are configured by the administrator and are not restricted to a predefined enum.
• direction identifies whether the order is a forward (F) or reverse (R) order.

Updates properties of an existing order.

The endpoint supports updating the order status, tags, custom fields, COD state, pause or resume state, and delivery address based on the supplied parameters and the current order stage.

Features

• Update the order status.
• Add tags to an order.
• Remove tags from an order.
• Update custom order fields.
• Update COD state.
• Pause an order.
• Resume a paused order.
• Update the delivery address when permitted.
• Update multiple order properties in a single request.

Tags

The tags parameter accepts comma-separated tag names.

• A tag without a - prefix is added to the order.
• A tag with a - prefix is removed from the order.

For example:

tags=Tag 2,case,try,-tag5,-123

adds Tag 2, case, and try, and removes tag5 and 123.

Order Status

The status parameter updates the order to the specified processing stage.

Order stages are configured separately for forward (F) and reverse (R) orders.

The supplied status must be a valid stage for the order direction. Otherwise, the request results in a 400 Bad Request response.

Notes

• At least one of status, claim, uid, or tags is required when the request is not authenticated against a customer contact.
• Tags can be added and removed using the tags parameter.
• Prefix a tag with - to remove it.
• The status value must be valid for the order's direction.
• delivery_address cannot be changed by a customer after the first configured order stage.
• pause=true pauses the order.
• resume=true resumes the order.
• cod=true updates the order as a cash-on-delivery order.

Applies a coupon to an existing order.

The supplied coupon code is validated and applied to the order. After applying the coupon, the order and invoice details are recalculated and the updated order details are returned.

Features

• Apply a coupon to an existing order.
• Recalculate the order after applying the coupon.
• Return the updated order details.
• Return the updated invoice details.
• Return coupon savings applied to the order.
• Return all coupons currently applied to the order.
• Return updated loyalty information.

Coupon

The coupon query parameter is mandatory.

The coupon value should contain the configured coupon code.

Example:

coupon=TEST6

Multiple coupons can be applied to the same order by calling this endpoint with additional valid coupon codes.

Previously applied coupons remain associated with the order.

Notes

• The coupon parameter is mandatory.
• The supplied coupon code is validated before it is applied.
• Applying a coupon recalculates the order and invoice.
• The response contains the complete updated order state.
• The coupons array contains coupons currently applied to the order.
• item_savings.coupons contains the coupon savings applied to order items.
• Coupon savings can change when another coupon is applied.

Processes an individual item in an order during the current order processing stage.

The endpoint records the processing result for the specified item, including successfully processed quantity and any configured processing causes.

The processing stage must already be claimed for the order before an item can be processed.

Features

• Process an individual order item.
• Record successfully processed quantity.
• Record processing quantities against configured causes.
• Mark an item as successfully processed.
• Mark an item with one or more processing causes.
• Set the COD amount during the delivery stage.
• Complete the current processing stage after all required items are processed.
• Automatically update the order status when the processing stage is completed.
• Mark the order as stuck when processing causes are present.

Processing Parameters

The request accepts only the following query parameters:

• success - Quantity successfully processed.
• cause.<id> - Quantity associated with a configured processing cause.
• amount - COD amount to be set during the delivery stage.

Multiple cause.<id> parameters can be supplied for the same item.

The value of every quantity parameter must be numeric.

Item Processing

When an item ID is supplied, the total quantity specified by success and all cause.<id> parameters must exactly match the quantity ordered for that item.

For example, an item with quantity 5 can be processed as:

success=3&cause.12=2

The total processed quantity is 5.

If the processed quantity does not match the ordered quantity, the request is rejected.

Processing Causes

Processing causes are configured for the current processing stage.

Each cause.<id> parameter must reference a valid cause configured for the current processing stage.

When a non-zero cause quantity is recorded, the corresponding cause is associated with the order and the order is marked as stuck.

Existing causes for the order are preserved while processing additional items.

Complete Processing Stage

Use _ as the item_id to indicate that processing of the current stage is complete.

Before completing the stage, the endpoint verifies that all required items have been processed.

For product-processing stages, every order item must have a corresponding processing entry.

If any required item has not been processed, the stage cannot be completed.

When the stage is successfully completed, the order is moved to the next configured status.

COD Amount

The amount parameter can be supplied when processing the delivery stage to set the COD amount for the order.

Example:

amount=500

Notes

• The order must already be claimed before an item can be processed.
• success represents successfully processed quantity.
• cause.<id> represents quantity associated with a specific processing cause.
• The sum of all processing quantities must match the ordered quantity for the item.
• cause.<id> must reference a valid cause for the current processing stage.
• item_id=_ completes the current processing stage.
• A product-processing stage cannot be completed while any required item remains unprocessed.
• An order with processing causes is marked as stuck.
• The processing result is stored against the current processing stage.
• If the order is already stuck when completing the stage, no further status update is performed.
• The endpoint returns the updated order information when the processing stage is completed.

Permissions

Any of the following permissions are needed

• Orders/manage
• Orders/process

Updates the items of an existing e-commerce order.

This endpoint allows the quantity, price, and discount of existing order items to be updated.

Features

• Update the quantity of an existing order item.
• Update the price of an existing order item.
• Update the discount of an existing order item.
• Add a new item to an existing order.
• Remove an item by setting its quantity to zero.

Updates custom parameters associated with an existing order.

Order parameters are supplied as query parameters using the param. prefix. Each parameter name after the prefix is stored against the order.

Features

• Update custom parameters associated with an order.
• Support multiple parameters in a single request.
• Support comma-separated values for multi-choice parameters.
• Return whether the order requires recalculation.

Parameter Format

Order parameters must use the following format:

param.<parameter_name>=<value>

Multiple parameters can be supplied in the same request.

Example:

param.student type=Foundation

param.batch=11

param.multichoice=C2,C1,C3

The param. prefix identifies the parameter as an order parameter.

Notes

• Parameter names after the param. prefix are dynamic.
• Multiple param.* parameters can be supplied in the same request.
• A comma-separated value can be used for parameters that accept multiple selections.
• The response indicates whether the order requires recalculation.
• The endpoint updates the parameters of the specified existing order.

Creates a return for one or more items from an existing order.

The endpoint supports both return-only requests and exchanges.

Features

• Return one or more items from an existing order.
• Specify the quantity being returned.
• Provide a reason for the return.
• Optionally exchange a returned item for another item.
• Return the ID of the newly created return order.
• Return the ID of the newly created exchange order when an exchange is requested.

Item IDs

Each return item uses the following fields:

• id - ID of the item that was originally purchased in the order and is being returned.
• quantity - Quantity of the purchased item being returned.
• reason - Reason for returning the item.
• exch_id - ID of the new item requested as an exchange.
• exch_quantity - Quantity of the new item requested for exchange.

Return Only

A return can be created without an exchange by providing only the original item ID, return quantity, and reason.

Example:

/aalam/ecomm/order/HIFU7298/returns

{
  "items": [
    {
      "id": 267,
      "quantity": 1,
      "reason": "Damaged"
    }
  ]
}

Exchange

When an exchange is requested, exch_id identifies the newly selected item and exch_quantity specifies the quantity required.

Example:

{
  "items": [
    {
      "id": 294,
      "quantity": 1,
      "exch_id": 13,
      "exch_quantity": 1
    }
  ]
}

Notes

• id always refers to an item from the original order.
• reason describes why the original item is being returned.
• exch_id and exch_quantity are optional.
• If no exchange fields are supplied, only a return order is created.
• When exchange fields are supplied, an exchange order is also created.
• At least one return item must be supplied.

Splits an existing order into multiple separate orders.

The items from the original order can be distributed between multiple split orders. Each split order can also be assigned an order processing status.

Features

• Split one order into multiple orders.
• Distribute products between the resulting orders.
• Specify the quantity of each item in each split order.
• Set the processing status for each split order.
• Split an already split order again.
• Support multiple levels of order splitting.

Split Items

The id in each item refers to the item ID from the original order being split.

quantity specifies how much of that item should be included in the particular split order.

All quantities from the original order must be accounted for across the split plan.

Split Status

Each split entry must contain a status.

The status must be a valid order processing status for the direction of the parent order.

Processing statuses are configured by the administrator and are not restricted to a predefined enum.

Multiple Splits

An order can be split into multiple orders.

A previously split order can also be split again, provided it has not reached the shipped stage.

This allows multiple levels of splitting.

For example:

• NZRL6451 can be split into NZRL6451-1 and NZRL6451-2.
• NZRL6451-2 can subsequently be split into additional child orders.
• The resulting order numbers continue the split relationship with the original order.

Notes

• At least two split entries must be supplied.
• Every split entry must contain status and items.
• The split plan must account for all items and their quantities from the order.
• An item quantity cannot exceed the quantity available in the parent order.
• The order cannot be split after it has reached the shipped stage.
• An order that is already split cannot be split again at the same split stage.
• The parent order must exist.
• The split status must be valid for the parent order direction.

Permissions

Orders/manage is needed

Retrieves orders matching the supplied filters.

Orders can be filtered, sorted, limited, or downloaded based on the supplied query parameters.

Features

• Retrieve orders using multiple filter criteria.
• Filter orders by status, direction, customer, and order state.
• Filter orders by stuck or on-hold state.
• Sort orders using multiple supported fields.
• Limit the number of returned orders.
• Select specific response fields.
• Request order summary information.
• Download order data with optional address and item details.

Order Status

The status value is not restricted to a predefined enum.

Order processing statuses are configured by the administrator and can differ between installations.

• Configured processing statuses can be used for both forward (F) and reverse (R) order flows.
• Cancelled is a predefined status and is available for both forward and reverse orders.
• Abandoned is a predefined status and is available only for forward (F) orders.
• If an unavailable status is supplied, an empty array is returned.

Direction

The direction parameter identifies the order flow.

• F - Forward order.
• R - Reverse order.

Abandoned status is valid only for F direction.

Notes

• Multiple sorting expressions can be supplied as a comma-separated list.
• Invalid filter fields or filter syntax result in a 400 Bad Request response.
• Invalid sort fields or sort methods result in a 400 Bad Request response.
• summary is not available for customer users.
• When download is requested, pagination, field selection, and sorting parameters are removed.
• address controls whether address details are included in downloaded data.
• items controls whether item details are included in downloaded data.

Creates a new forward order for a customer.

Internal users can create an order by providing the customer contact ID and the items to be ordered.

Customer users can create an order using the items available in their cart.

Features

• Create a new forward (F) order.
• Create an order with multiple items.
• Specify item quantity, price, and discount.
• Create an order from the authenticated customer's cart.
• Validate the supplied customer and item IDs.
• Generate a unique order number automatically.
• Create an invoice automatically for the new order.
• Return the newly created order ID.

Notes

• Internal users must be administrators or have Orders manage permission.
• contact_id is required when an internal user creates an order.
• items is required when an internal user creates an order.
• Customer users use their authenticated contact automatically.
• Customer users must have items available in their cart.
• All supplied item IDs must be valid.
• A unique order number is generated automatically.
• An invoice is automatically created for the new order.
• The generated order number is stored in the invoice as Order Id.
• The endpoint creates only forward (F) orders.

Cancels an existing shipment associated with an order.

The endpoint retrieves the shipping service associated with the order and invokes that service's configured shipment cancellation API.

Features

• Cancel an existing shipment.
• Identify the shipping service from the order shipment details.
• Use the shipping service's configured cancellation API.
• Pass the order ID and order direction to the shipping service.
• Validate the response from the shipping service.

Shipment Validation

The order must already have shipping details.

If the order has not yet been shipped, the request is rejected.

The shipping service code is obtained from the existing shipment details. If the service code cannot be determined, the request is rejected.

Shipping Service

The shipping service associated with the order must provide a cancelshipment API.

If the configured shipping service does not provide a shipment cancellation API, the request is rejected.

The cancellation request sent to the shipping service contains:

• order_id - The order identifier.
• direction - The order direction (F or R).

Notes

• This endpoint uses the POST method.
• order_id identifies the order whose shipment is being cancelled.
• The shipping service is determined from the existing shipment details.
• The endpoint does not require the shipping service code as a request parameter.
• The cancellation operation is performed by the shipping service configured for the order.
• A non-200 response from the shipping service results in a 500 Internal Server Error.

Permissions

Orders/manage is needed

Retrieves tracking information for an existing shipment associated with an order.

The endpoint validates access to the order, verifies that the order has already been shipped, identifies the shipping service used for the shipment, and retrieves the tracking service configured for that shipping provider.

Features

• Track an existing order shipment.
• Support tracking for internal users.
• Validate that the order has already been shipped.
• Identify the shipping service associated with the order.
• Use the configured tracking API of the shipping service.

Shipment Validation

The order must already have shipping details.

If the order has not yet been shipped, the request is rejected.

The shipping service code is obtained from the existing shipment details. A valid shipping service code is required before tracking information can be retrieved.

Tracking Service

The configured shipping service must provide a track API.

If a tracking API is not available for the shipping service, the request is rejected.

Notes

• order_id identifies the order whose shipment is being tracked.
• The endpoint does not create or modify a shipment.
• The shipping service is determined from the existing shipment details.
• Tracking is performed using the shipping service's configured tracking API.
• Internal users require administrator access or Orders manage permission.

Creates a shipment for an existing order using the specified shipping service.

The shipping service is selected using the mandatory service query parameter. The package dimensions and serviceability check can also be supplied as query parameters.

Features

• Create a shipment for an existing order.
• Select the shipping service for the shipment.
• Check destination serviceability before shipment creation.
• Provide package length, breadth, and height.
• Support different configured shipping providers.
• Update the order through the selected shipping service.

Shipping Service

The service parameter identifies the configured shipping provider to use for shipment creation.

Supported services depend on the shipping providers configured for the installation.

Examples:

• aalam/bluedart
• aalam/shiprocket
• aalam/shipfast

Example using Blue Dart:

/aalam/ecomm/order/TELN2098/shipment?service=aalam%2Fbluedart&check=true&length=80&breadth=30&height=40

Example using Shiprocket:

/aalam/ecomm/order/TELN2098/shipment?service=aalam%2Fshiprocket&check=true&length=80&breadth=30&height=40

Serviceability Check

The check parameter can be used to check whether the destination is serviceable by the selected shipping service.

If the destination pincode is not serviceable, the request returns 406 Not Acceptable.

Package Dimensions

Package dimensions can be supplied using:

• length
• breadth
• height

Example:

length=80&breadth=30&height=40

Shipment Validation

Before creating a shipment:

• The order must have an address assigned.
• The order must be in a shippable processing stage.
• The requested shipping service must be configured.
• The selected shipping service must be able to process the destination.

Order Status

After shipment creation, the order can contain shipping details such as the cargo company, AWB number, and expected delivery date.

Example:

/aalam/ecomm/order/TELN2098?status=Shipped&Cargo+Company=comp&AWB+No=12345&Expected+DOD=18-08-2026

Notes

• service is mandatory.
• Shipping services are installation-dependent.
• check is optional.
• Package dimensions are optional.
• A customer address must be available.
• The order must be in a valid stage for shipment creation.
• Remote applications use the remote shipment creation flow.
• Internal users must be administrators or have Orders manage permission.

Checks the serviceability of available shipping services for an existing order.

The API evaluates the order destination against the configured shipping services and returns whether each service can serve the order.

Features

• Check shipping serviceability for an order.
• Return all configured shipping services.
• Identify which shipping services can serve the destination.
• Return the shipping service code and display name.
• Return the shipping service icon.
• Return an optional shipping service description.

Serviceability Result

Each configured shipping service is returned with a can_serve value.

• true means the shipping service can serve the order destination.
• false means the shipping service cannot serve the order destination.

Example:

• aalam/bluedart can serve the destination.
• aalam/shipfast cannot serve the destination.
• aalam/shiprocket cannot serve the destination.

Notes

• The order is identified using order_id.
• No shipping service needs to be specified in the request.
• The API checks all configured shipping services.
• The result can be used to select a shipping service before creating a shipment.

Permissions

Orders/manage is needed

Marks an existing shipment as cancelled for an order.

The endpoint first verifies that a shipment has already been created for the order and identifies the shipping service that created the shipment.

Features

• Validate that the order has an existing shipment.
• Identify the shipping service associated with the shipment.
• Ensure that the shipment cancellation request is made by the same shipping service that created the shipment.
• Reject cancellation requests from a different shipping service.

Shipment Validation

A shipment must already exist for the specified order.

If no shipping details are available, the request is rejected with a 400 Bad Request response.

The shipping service code is obtained from the existing shipment details. If the service code cannot be determined, the request is rejected.

Shipping Service Authorization

The authenticated user or remote shipping service must match the service that originally created the shipment.

A shipment created by one shipping service cannot be acknowledged or cancelled by another shipping service.

Notes

• The order_id identifies the order whose shipment is being cancelled.
• The order must already have shipping details.
• The shipping service code must be available for the existing shipment.
• Internal users are identified using the authenticated internal user context.
• Remote shipping services are identified using the authenticated remote service code.

Marks the shipment associated with an order as delivered.

The endpoint validates the shipment action user and the shipping service associated with the order before updating the order status.

Features

• Mark a shipment as delivered.
• Support both forward and reverse orders.
• Validate the authenticated shipment action user.
• Validate that the request is associated with the shipping service responsible for the order.
• Automatically select the appropriate delivered status based on the order direction.
• Preserve additional parameters supplied with the request.
• Update the order and trigger the corresponding order notifications.

Order Direction

The delivered status is selected automatically based on the order direction.

• Forward (F) orders are updated to the configured forward delivered status.
• Reverse (R) orders are updated to the configured reverse delivered status.

The caller does not need to provide the status parameter.

Shipping Service Validation

The authenticated user or remote shipping service must be authorized for the order shipment.

The endpoint validates the order shipper before updating the order. A request from an unauthorized shipping service is rejected.

Notes

• order_id identifies the order whose shipment is being marked as delivered.
• The status parameter is set internally by the endpoint.
• Additional query parameters are passed to the order update operation.
• The order must exist before it can be updated.
• The shipment action user must be authorized.
• The shipping service associated with the order must match the authenticated shipment service.
• Updating the order can trigger the configured order or return notification flow.
• For forward orders, the configured order notification is used.
• For reverse orders, the configured return notification is used.

Marks a reverse order shipment as picked.

This endpoint is used after a reverse shipment has been picked from the customer and moves the reverse order to the configured picked status.

Features

• Mark a reverse order shipment as picked.
• Validate the requested order before updating it.
• Validate that the shipment can be processed by the authenticated shipper.
• Preserve additional order parameters supplied in the request.
• Update the order status to the configured reverse shipment picked status.

Order Direction

This endpoint applies only to reverse (R) orders.

If the supplied order is a forward (F) order, the endpoint does not perform a status update.

Shipper Validation

The request must be made by an authorized shipment action user.

The shipment shipper is validated using either the authenticated internal user or the remote shipping service associated with the request.

Notes

• The status parameter is managed internally by the endpoint and is set to the configured reverse shipment picked status.
• Additional query parameters are passed to the order update operation.
• The order must exist before it can be marked as picked.
• The shipment must belong to the authenticated customer or authorized shipping service.
• This endpoint is intended for reverse shipment processing.

Marks a forward order shipment as stuck with a reason.

This endpoint is used when a shipment cannot proceed normally and requires attention or intervention.

Features

• Mark a forward order shipment as stuck.
• Record the reason for the shipment being stuck.
• Validate that the order is currently in the shipped stage.
• Avoid re-processing an order that is already marked as stuck.

Validation

The reason parameter is mandatory.

The endpoint applies only to forward (F) orders.

The order must currently be in the configured forward shipment stage. Orders in any other stage cannot be marked as stuck.

If the order is already marked as stuck, the operation returns without applying the operation again.

Notes

• order_id identifies the order whose shipment is being marked as stuck.
• reason must be supplied as a query parameter.
• The endpoint does not apply to reverse (R) orders.
• The order must already be in the shipped state.
• An already stuck order is not processed again.

Updates the registered shipping services.

The endpoint also supports checking the registered shipping services by supplying the check parameter.

Check Available Shipping Services

When the check parameter is present, the registered shipping services are rechecked.

Example:

/aalam/ecomm/service/shipping?check=1

The response contains the available shipping services.

Each shipping service contains:

• name - Shipping service name.
• code - Shipping service code.
• description - Shipping service description.
• icon - Shipping service icon path.
• cancelshipment - Indicates whether shipment cancellation is supported.
• track - Indicates whether shipment tracking is supported.

Example response:

[ { "name":"Shiprocket", "code":"aalam/shiprocket", "description":null, "icon":"/aalam/shiprocket/r/s/images/icon.png", "cancelshipment":true, "track":true }, { "name":"Shipfast", "code":"aalam/shipfast", "description":null, "icon":"/aalam/shipfast/r/s/images/icon.png", "cancelshipment":true, "track":true } ]

Update Shipping Services

The endpoint is also used for updating the registered shipping service configuration.

The exact update parameters depend on the remaining update logic of the update_shipping_services method.

Permissions

Any of the following permissions are needed

• Settings/configure
• Orders/manage

Registers a shipping service with the ecommerce system.

The shipping service must provide a name and a newshipment API. The service can optionally provide serviceability, tracking, cancellation, icon, and description details.

The shipping service registration requires internal authentication.

Register Shipping Service

Example:

/aalam/ecomm/service/shipping

Example request:

PUT /aalam/ecomm/service/shipping

Example payload:

{"name":"Shiprocket","icon":"/aalam/shiprocket/r/s/images/icon.png","serviceability":"/aalam/shiprocket/serviceability","track":"/aalam/shiprocket/track","cancelshipment":{"method":"POST","url":"/aalam/shiprocket/cancel"},"newshipment":{"method":"PUT","url":"/aalam/shiprocket/newshipment"}}

New Shipment API

The newshipment parameter is mandatory.

It defines the API used to create a new shipment.

The value can be supplied as a URL string.

Example:

"/aalam/shiprocket/newshipment"

A URL can also be supplied as an object with an HTTP method and URL.

Example:

{"method":"PUT","url":"/aalam/shiprocket/newshipment"}

When supplied as a string, the method defaults to GET.

Serviceability API

The serviceability parameter defines the API used to check whether shipping is available.

It can be supplied as a URL string or as an object containing method and url.

Example:

"/aalam/shiprocket/serviceability"

Example:

{"method":"POST","url":"/aalam/shiprocket/serviceability"}

When supplied as a string, the method defaults to GET.

Tracking API

The track parameter defines the API used to track a shipment.

It can be supplied as a URL string or as an object containing method and url.

Example:

"/aalam/shiprocket/track"

When supplied as a string, the method defaults to GET.

Cancel Shipment API

The cancelshipment parameter defines the API used to cancel a shipment.

It can be supplied as a URL string or as an object containing method and url.

Example:

{"method":"POST","url":"/aalam/shiprocket/cancel"}

When supplied as a string, the method defaults to GET.

Icon

The icon parameter can contain the URL or path of the shipping service icon.

Example:

"/aalam/shiprocket/r/s/images/icon.png"

Description

The description parameter can contain a description of the shipping service.

Permissions

• Allowed for all internal applications

Returns shipping properties for the requested object.

The obj path parameter determines the type of shipping property being requested.

Supported object types are:

• default - Returns the default shipping properties.
• item_type - Returns shipping properties for one or more item types.
• boxes - Returns the configured shipping boxes.

Default Shipping Properties

Use default as the obj and _ as the obj_id.

Example:

/aalam/ecomm/shipping_properties/default/_

Example response:

{"weight":500.0,"ship_estimate":3,"restrict_regions":null,"restrict_returns":null,"restrict_exchanges":[14,15,17,18],"return_due_days":"5"}

The restrict_regions, restrict_returns, and restrict_exchanges values contain shipping region IDs.

Item Type Shipping Properties

Use item_type as the obj.

One or more item type IDs can be provided as a comma-separated value in obj_id.

Example:

/aalam/ecomm/shipping_properties/item_type/1,2,3,4,5

When multiple item type IDs are supplied, the response is an array containing the ID and shipping properties of each item type.

Example response:

[ {"id":1,"props":{"weight":502.0,"ship_estimate":3,"restrict_regions":null,"restrict_returns":null,"restrict_exchanges":null,"return_due_days":null}}, {"id":2,"props":{}}, {"id":3,"props":{"weight":900.0,"ship_estimate":null,"restrict_regions":null,"restrict_returns":null,"restrict_exchanges":null,"return_due_days":null}} ]

If no shipping properties are configured for an item type, the props object is returned as an empty object.

Shipping Boxes

Use boxes as the obj and * as the obj_id.

Example:

/aalam/ecomm/shipping_properties/boxes/*

Example response:

[ {"name":"packaging box","l":100.0,"b":40.0,"h":50.0}, {"name":"return delivery","l":80.0,"b":30.0,"h":40.0} ]

The l, b, and h values represent the length, breadth, and height of the shipping box.

Permissions

Settings/configure is needed

Creates or updates shipping properties for the specified object.

The shipping properties can be updated for an item, item type, the default shipping configuration, or a shipping box.

Item Shipping Properties

Use item as the obj and provide the item ID as obj_id.

Example:

/aalam/ecomm/shipping_properties/item/9?return_due_days=7&restrict_regions=14%2C2&restrict_returns=19%2C3

The following shipping properties can be configured:

• weight - Item weight.
• ship_estimate - Shipping estimate.
• restrict_regions - Shipping region IDs where shipping is restricted.
• restrict_returns - Shipping region IDs where returns are restricted.
• restrict_exchanges - Shipping region IDs where exchanges are restricted.
• return_due_days - Number of days allowed for return.

Multiple shipping region IDs must be supplied as a comma-separated value.

Example:

/aalam/ecomm/shipping_properties/item/10?restrict_exchanges=14%2C15%2C18

A successful update returns an empty response with HTTP status 200.

Item Type Shipping Properties

Use item_type as the obj and provide the item type ID as obj_id.

Example:

/aalam/ecomm/shipping_properties/item_type/1?ship_estimate=5&restrict_regions=1%2C12%2C14%2C2%2C3

This updates the shipping properties for item type ID 1.

Multiple item type IDs can also be supplied as a comma-separated value.

Example:

/aalam/ecomm/shipping_properties/item_type/1,2,3?ship_estimate=5

The restrict_regions, restrict_returns, and restrict_exchanges values contain comma-separated shipping region IDs.

A successful update returns an empty response with HTTP status 200.

Default Shipping Properties

Use default as the obj and _ as the obj_id.

Example:

/aalam/ecomm/shipping_properties/default/_?restrict_regions=1%2C2

This updates the default shipping properties.

A successful update returns an empty response with HTTP status 200.

Shipping Boxes

Use boxes as the obj and provide the box name as obj_id.

If the specified box already exists, its dimensions are updated.

Example:

/aalam/ecomm/shipping_properties/boxes/return%20delivery?l=60&b=50&h=35

The following dimensions are supported:

• l - Box length.
• b - Box breadth.
• h - Box height.

If the specified box does not already exist, a new shipping box is created.

Example:

/aalam/ecomm/shipping_properties/boxes/small%20box?l=50&b=30&h=20

Shipping Region IDs

The values supplied for restrict_regions, restrict_returns, and restrict_exchanges are shipping region IDs.

Example:

restrict_regions=14,2

restrict_returns=19,3

restrict_exchanges=14,15,18

Permissions

Settings/configure is needed