Attachment - 1578298317573110001 - Attach - 137975909564870000 - 1578298317573110001 - SalesOrders API

Introduction
The Zoho Commerce API allows you to perform all the operations that you do with our web
client. Zoho Commerce API is built using REST principles which ensures predictable URLs that
makes writing applications easy. This API follows HTTP rules, enabling a wide range of HTTP
clients can be used to interact with the API. Every resource is exposed as a URL. The URL of each
resource can be obtained by accessing the API Root Endpoint.
OAuth
Zoho REST APIs uses the OAuth 2.0 protocol to authorize and authenticate calls (The above
approach of authentication via Authtoken will be deprecated soon). It provides secure access to
protect resources thereby reducing the hassle of asking for a username and password everytime
a user logs in. Follow the steps listed here, to access Zoho’s APIs using OAuth 2.0
Step 1: Registering New Client

You will have to first register your application with Zoho's Developer console in order get your
Client ID and Client Secret.
To register your application, go to https://accounts.zoho.com/developerconsole and click on Add

Client ID. Provide the required details to register your application.
On successful registration, you will be provided with a set of OAuth 2.0 credentials such as a
Client ID and Client Secret that are known to both Zoho and your application. Do not share this
credentials anywhere.
Step 2: Generating Grant Token

Redirect to the following authorization URL with the given params
https://accounts.zoho.com/oauth/v2/auth?
Parameter Description
scope * SCOPE for which the token to be generated.

Multiple scopes can be given which has to be
separated by commas.
Ex : ZohoCommerce.fullaccess.all
client_id * Client ID obtained during Client
Registration state. An opaque string that is
round-tripped in the protocol; ie., whatever
value given to this will be passed back to you.
response_type * code
redirect_uri * One of the redirect URI given in above step.

This param should be same redirect url
mentioned while registering the Client
access_type The allowed values are offline and online. The

online access_type gives your application only
the access_token which is valid for one hour.
The offline access_type will give the
application an access_token as well as a
refresh_token. By default it is taken as online.
prompt Prompts for user consent each time your app

tries to access user credentials. Ex: Consent
Note: Fields with * are mandatory

On this request, you will be shown with a "user consent page".
Upon clicking “Accept”, Zoho will redirect to the given redirect_uri with code and state param.
This code value is mandatory to get the access token in the next step and this code is valid for 60
seconds.
On clicking “Deny”, the server returns an error
Step 3: Generate Access and Refresh Token

After getting code from the above step, make a POST request for the following URL with given
params, to generate the access_token.
https://accounts.zoho.com/oauth/v2/token?
code* code which is obtained in the above step
client_id * Client ID obtained during Client Registration
client_secret* Client secret obtained during Client

Registration
redirect_uri* This param should be same redirect url
mentioned while adding Client
grant_type* authorization_code
scope SCOPE for which token to be generated. Ex :

ZohoBooks.fullaccess.all. Multiple scopes has
to be separated by commas.
state An opaque string that is round-tripped in the

protocol; that is to say, value will be passed
back to you.
Note: Fields with * are mandatory

In the response, you will get both access_token and refresh_token.
1. The access_token will expire after a particular period (as given in expires_in param in the
response).
2. The refresh_token is permanent and will be used to regenerate new access_token, if the
current access token is expired.
Note: Each time a re-consent page is accepted, a new refresh token is generated. The maximum
limit is 20 refresh tokens per user. If this limit is crossed, the first refresh token is automatically
deleted to accommodate the latest one. This is done irrespective of whether the first refresh
token is in use or not.
Step 4: Generate Access Token From Refresh Token

Access Tokens have limited validity. In most general cases the access tokens expire in one hour.
Until then, the access token has unlimited usage. Once it expires, your app will have to use the
refresh token to request for a new access token. Redirect to the following POST URL with the
given params to get a new access token
refresh_token REFRESH TOKEN which is obtained in the

above step
client_id Client ID obtained during Client Registration
client_secret Client secret obtained during Client

Registration
redirect_uri This param should be same redirect url
mentioned while registering Client
grant_type refresh_token

Request Example :
Step 5: Revoking a Refresh Token

To revoke a refresh token, call the following POST URL with the given params
refresh_token REFRESH TOKEN which is to be revoked
Request Example :
Step 6: Calling An API
Access Token can be passed only in header and cannot be passed in the request param.
Header name should be Authorization
Header value should be Zoho-oauthtoken {access_token}
Organization ID
In Zoho Commerce, your business is termed as an organization. If you have multiple businesses,
you simply set each of those up as an individual organization. Each organization is an
independent Zoho Commerce Organization with it’s own organization ID, base currency, time
zone, language, contacts, reports, etc.
The parameter organization_id along with the organization ID should be sent in with every API
request to identify the organization.
The organization_id can be obtained from the GET /organizations API’s JSON response.
Alternatively, it can be obtained from the Manage Organizations page in the admin console:
Login to the Zoho Inventory admin console. Click the drop down with organization’s name as the
label and click Manage Organizations.
Request Example
RESPONSE
HTTP Methods
Zoho Commerce API uses appropriate HTTP verbs for every action.
Method Description
GET Used for retrieving resources.
POST Used for creating resources and performing

resource actions.
DELETE Used for deleting resources.
Using GET method, you can get the list of resources or details of a particular instance of a
resource.
To get a list of salesorders
To get the details of a contact referred to by a specified salesorder_id

Response
Responses will be in the JSON format.
Node Name Description
code Zoho Commerce error code. This will be zero

for a success response and non-zero in case of
an error.
message Message for the invoked API.
resource name Comprises the invoked API’s Data.
The response structure for the salesorders API follows the below format.
SUCCESS
Other Formats
Certain APIs support csv and pdf formats as well for which the required response format needs
to be specified in the respective request’s Accept header or accept query parameter.
Date
All timestamps are returned in the ISO 8601 format - YYYY-MM-DDThh:mm:ssTZD.
Example: 2016-06-11T17:38:06-0700
Request Example
Response Header Example
Errors
Zoho Commerce uses HTTP status codes to indicate success or failure of an API call. In general,
status codes in the 2xx range means success, 4xx range means there was an error in the provided
information, and those in the 5xx range indicate server side errors. Commonly used HTTP status
codes are listed below.
HTTP Status Codes
Status Code Description
200 Success: The request was successfully

completed.
201 Created: The request was a success and one

or more resources have been created.
400 Bad request: The request cannot be

performed. Usually because of malformed
parameter or missing parameter.
401 Unauthorized (Invalid AuthToken): Request

was rejected because of invalid AuthToken.
404 URL Not Found: The URL you’ve sent is

wrong. It’s possible that the resource you’ve
requested has been moved to another URL.
405 Method Not Allowed: The requested

resource does not support the HTTP method
used. For example, requesting List of all
salesorders API with PUT as the HTTP
method.
429 Too many requests: Too many requests

within a certain time frame. To know more
about api call limits, click here.
500 Server error: Zoho Commerce server

encountered an error which prevents it from
fulfilling the request. Although this rarely
happens, we recommend you to contact us
at support@zohocommerce.com if you
receive this error.
Request Example
Response Example
FAILURE
Pagination
Zoho Commerce provides APIs to retrieve lists of products, salesorders and other resources -
paginated to 200 items by default. The pagination information will be included in the list API
response under the node name page_context.
* By default first page will be listed. For navigating through pages, use the page parameter.
* The per_page parameter can be used to set the number of records that you want to receive in
response.
Example
SUCCESS
API Call Limit
API calls are limited to provide better quality of service and availability to all the users. You can
send a maximum of 1000 API requests per day per organization during the free plan. However, if
the organization is on a paid plan you can send up to 2500 API requests per day per
organization.
SalesOrders
A sales order is a financial document that confirms an impending sale. It details the exact
quantity, price and delivery details of the products or services being sold. Perform the simple
operations mentioned below to retrieve your Sales Orders.
OAuthScope
ZohoCommerce.salesorders.ALL
Headers
Header Values
Authorization Zoho-oauthtoken
1001.c827a747d852fea057e71b1a526c69cf.
bf9e2c6d2640506d00793a215c871989
X-com-zoho-store-organizationid 58927961
Attributes
Attribute Description
salesorder_id long: Unique ID generated by the server for
the Sales Order. This is used as identifier.
salesorder_number string: The Sales Order number. This is unique
for each sales order.
date string: The date for the Sales Order.
order_status string: The current status of the Sales Order.
Allowed
Values: pending, confirmed, completed, retu
rned, cancelled and declined.
shipment_date string: Shipment date of the Sales Order.
reference_number string: Reference number of the Sales Order.
customer_id long: Unique ID generated for the customer.
This is used as an identifier.
customer_name string: Name of the customer.
currency_id long: Unique ID generated by the server for
the currency. This is used as an identifier.
currency_code string: Currency code.
currency_symbol string: The symbol for the selected currency.
total double: Total amount of the Sales Order.
is_emailed boolean: Checks whether the Sales Order has
been emailed to the customer or not.
created_time string: Time at which the Sales Order was
created.
last_modified_time string: Time at which the sales order details
were last modified.
contact_persons list: Person/Individual who represents a
company
billing_address object: Billing address of the contact.
shipping_address object: Customer's shipping address to which
the goods must be delivered.
exchange_rate double: Exchange rate of the currency, with
respect to the base currency.
discount_amount double: Discount to be applied on the Sales
Order.
discount double: The percentage of Discount applied.
discount_type string: Type of discount.
Allowed values are entity_level,item_level.
For entity_level type, discount is applied at
entity level and the node discount resides
outside the line_items node.For item_level
type, discount is applied at item level and the
node discount resides inside each line_item
under the line_items node
line_items list: A sales order can contain multiple line
items. Each line item contains item_id, name,
description, rate, quantity, unit, tax_id,
tax_name, tax_type, tax_percentage,
item_total.
shipping_charge double: Shipping charges that can be applied
to the Sales Order.
adjustment double: Adjustment on the Sales Order's
total.
adjustment_description string: Description for the adjustment.
sub_total double: Sub total of the Sales Order.
tax_total double: Tax total of the Sales Order.
taxes list: Number of taxes applied on sales order.
Each tax contains: tax_name and tax_amount.
price_precision integer: The precision level for the price's
decimal point in a Sales Order.
packages list: These are the packages created for Sales
Orders. Each package contains - package_id,
package_number, status, detailed_status,
status_message, shipment_id,
shipment_number, shipment_status, carrier,
service, tracking_number, shipment_date,
delivery_days and delivery_guarantee.
notes string: Notes for the Sales Order.
terms string: Terms for the Sales Order.
invoiced_status string: The current status of the invoice.
Allowed Values: paid, unpaid, refunded,
cancelled and declined.
shipped_status string: The current status of the package.
Allowed Values: paid, unpaid, refunded,
cancelled and declined.
payment_mode string: Mode through which payment is
made.
This can be Cash On Delivery, Razorpay,
Stripe or others. Maximum length [100].
is_offline_payment boolean: Checks whether the payment was
made offline.
List all Sales Orders
List all SalesOrders :

Lists all the available Sales Orders in Zoho Commerce.
HTTP Request
GET https://commerce.zoho.com/store/api/v1/salesorders
Query Parameters
Parameter Values
filter_by Status.All, Status.Draft, Status.Confirmed,
Status.ToBePacked, Status.ToBeShipped,
Status.Shipped, Status.ToBeInvoiced,
Status.Closed, Status.Void
sort_column customer_name, salesorder_number, date,
shipment_date, total, bcy_total, created_time,
last_modified_time
sort_order A, D
page_start_from 1 to n
per_page 10,25,50,100,200
Search Nodes
Parameter Values
customer_id 3000000002259
salesorder_number_contains SO-00002
email peterparker@bowmanfurniture.com
mobile 9876543210
order_status draft,pending,confirmed,closed,void,onhold,ca
ncelled
invoiced_status null,partially_invoiced,invoiced,paid
paid_status null,unpaid,partially_paid,paid
shipped_status null,pending,partially_shipped,shipped,fulfille
d
return_status null,initiated,partially_returned,returned
return_shipment_status null,receive_pending,partially_received,receiv
ed
refund_status null,refund_pending,partially_refunded,refund
ed
is_return_waiting_for_approval true,false
is_cancel_item_waiting_for_approval true,false
Request Example
Response Example
SUCCESS
Retrieve a Sales Order
Retrieve a Sales Order :
Retrieves the details for an existing Sales Order.
HTTP Request
GET https://commerce.zoho.com/store/api/v1/salesorders/order_id
Request Example
Response Example
SUCCESS
Update Status
Update Status
Changes the status of a Sales Order.
POST https://commerce.zoho.com/store/api/v1/salesorders/{salesorder_id}/status/{status}
Status values
Status Description
confirmed To mark salesorder as Confirmed
void To mark salesorder as Declined
cancelled To mark salesorder as Cancelled
Request Example
Response Example
SUCCESS
Add Comments
Add Sales Order Comments:
Use this API to add comments to your salesorder.
HTTP Request:
POST https://commerce.zoho.com/store/api/v1/salesorders/{salesorder_id}/comments
Body Parameters
description string: The comment to be added
show_comment_to_client boolean: Boolean to determine whether the

comment needs to be shown to client
mail_to_customer boolean: Boolean to determine whether it has

to be mailed to the customer
transaction_type string: Allowed values : salesorder,

customer_payment, shipment_order, contact.
none.
Request Example
SUCCESS
FAILURE
Update address
Update Address :
Use this API to update addresses of your salesorder pizza.
HTTP Request :
PUT
https://commerce.zoho.com/store/api/v1/salesorders/{salesorder_id}/address/{address_type
}
Address types
Type Description
billing To update the billing address
shipping To update the shipping address
Body Parameters
attention string: Name of the person, whose attention

is required.
address string: Name of the street of the customer’s

billing address.
city string: Name of the city of the customer’s

billing address.
state string: Name of the state of the customer's

billing address.
zip string: Zip code of the customer’s billing

address.
country string: Name of the country of the customer’s

billing address.
fax string: Fax number of the customer’s billing

address.
phone string: Phone number of the customer
Request Example
Response Example
SUCCESS
FAILURE
Shipment Orders
Shipment Orders
A document used by an organization to specify what items or packages are to be transferred
from a storage location or warehouse to what person and to what new location is called a
shipment order. It is typically sent along with a shipment of goods so that the person receiving
them(your customer) can verify that the document correctly reflects the items that they actually
received.
Attributes
salesorder_id string: Unique ID generated by the server for
tracking_number string: Tracking number of shipment.
carrier string: Carrier used for shipment.
service string: Type of service selected for shipment
tracking_url string: The tracking url of the shipment

Mark as Shipped
Mark as Shipped
Use this API to mark your order as shipped
POST
https://commerce.zoho.com/store/api/v1/salesorders/{salesorder_id}/shipmentorders/shipp
ed
Body Params
Request Example
Response Example
SUCCESS
FAILURE
Mark as Delivered
Mark as Delivered
Use this API to mark your salesorder as delivered.
POST
https://commerce.zoho.com/store/api/v1/salesorders/{salesorder_id}/shipmentorders/deliver
ed
Body Params
delivery_date string: Date of delivery of the product.
Request Example
Request Example
SUCCESS
FAILURE
Update Shipment Order
Update a Shipment Order:
Use this API to update the details of a shipment order.
HTTP Request:
PUT https:/commerce.zoho.com/store/api/v1/salesorders/{salesorder_id}/shipmentorders
Attributes
salesorder_id string: Unique ID generated by the server for
Request Example
Response Example
SUCCESS
FAILURE
Customer Payments
Customer Payments
A payment object describes details regarding a particular customer payment. There can be
multiple payments for a single invoice. Multiple invoices can be paid in a single payment as well.
Attributes
payment_mode string: Mode through which payment is made.

This can be check, cash, creditcard,
banktransfer, bankremittance,
autotransaction or others.
Maximum length [100]
reference_number string: Reference number generated for the

payment. A string of your choice can also be
used as the reference number. Maximum
length of the reference number [100]
date string: Date on which payment is made. Date

Format [yyyy-mm-dd]
description string: Description about the payment.
payment_id string: Unique ID of the payment generated

by the server. Maximum length allowed
[2000]
payment_mode double: Exchange rate for the currency used

in the invoices and customer's currency. The
payment amount would be the multiplicative
product of the original amount and the
exchange rate.
amount double: Amount paid in the respective

payment.
invoice_id string: Invoice ID of the required invoice.

Mark as Paid
Mark as Paid
Use this API to mark your unpaid order as paid.
POST
https://commerce.zoho.com/store/api/v1/salesorders/51128000000104005/payments
Parameters
payment.

Format [yyyy-mm-dd]
Request Example
Response
SUCCESS
FAILURE
Update Payment
Update Payment
Use this API to update payment information.
PUT
https://commerce.zoho.com/store/api/v1/salesorders/{salesorder_id}/payments/{payment_id
}
Attributes


payment.


Format [yyyy-mm-dd]
Request Example
Response Example
SUCCESS
FAILURE
Refund Payment
Refund Payment
Use this API to refund your payment.
POST https://commerce.zoho.com/store/api/v1/salesorders/{salesorder_id}/refund
Parameters
amount double: Amount to be refunded.
Request Example
Response
SUCCESS
FAILURE
Create a Sales Return
Create a Sales Return:
Use this API to create a salesreturn from your salesorder
HTTP Request
POST https://commerce.zoho.com/store/api/v1/salesreturns
Query Parameters
salesorder_id long: Unique ID generated by the server for

Body Parameters
line_items list: List of items in a package. Each line item

contains salesorder_item_id, item_id and
quantity,
salesorder_item_id (or) long: Unique ID generated by the server for

line_item_id each line item. This is used as an identifier.
quantity integer: Quantity of the item to be returned
Request Example
SUCCESS
FAILURE
Change Status
Change Status :
To change the status of a salesreturn.
HTTP Request :
POST
https://commerce.zoho.com/store/api/v1/salesreturns/{salesreturn_id}/status/{salesreturn_s
tatus}
Attributes
salesreturn_id long: Unique ID generated by the server for
the Sales Return. This is used as identifier.
salesreturn_status string: The current status of the salesreturn.
shipped_status string: The current status of the package.
refund_status string: The current status of the refund

quantity.
Statuses
Status Description
approved string: To approve the status of the
salesreturn
declined string: To decline the status of the

salesreturn.
Request Example
Response Example
SUCCESS
FAILURE
Refund a SalesReturn
Refund a SalesReturn:
Use this API to refund your sales return.
HTTP Request:
POST https://commerce.zoho.com/store/api/v1/salesreturn/{salesreturn_id}/refund
Query Parameters
salesreturn_id long: Unique ID generated by the server for

Body Parameters
salesreturn_item_id long: Unique ID generated by the server for

quantity.
amount double: Amount to be refunded.
quantity integer: Quantity of the item to be returned
is_returned_to_stock boolean: Add product to stock. Allowed

values are true and false.
Request Example
Response
SUCCESS
FAILURE

Attachment - 1578298317573110001 - Attach - 137975909564870000 - 1578298317573110001 - SalesOrders API

Uploaded by

Copyright:

Available Formats

You might also like

Attachment - 1578298317573110001 - Attach - 137975909564870000 - 1578298317573110001 - SalesOrders API

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Attachment - 1578298317573110001 - Attach - 137975909564870000 - 1578298317573110001 - SalesOrders API

Uploaded by

Copyright:

Available Formats

Introduction

Step 1: Registering New Client

To register your application, go to https://accounts.zoho.com/developerconsole and click on Add

Step 2: Generating Grant Token

scope * SCOPE for which the token to be generated.

redirect_uri * One of the redirect URI given in above step.

access_type The allowed values are ofﬂine and online. The

prompt Prompts for user consent each time your app

Note: Fields with * are mandatory

Step 3: Generate Access and Refresh Token

code* code which is obtained in the above step

client_id * Client ID obtained during Client Registration

client_secret* Client secret obtained during Client

scope SCOPE for which token to be generated. Ex :

state An opaque string that is round-tripped in the

Note: Fields with * are mandatory

Step 4: Generate Access Token From Refresh Token

refresh_token REFRESH TOKEN which is obtained in the

client_id Client ID obtained during Client Registration

client_secret Client secret obtained during Client

Step 5: Revoking a Refresh Token

refresh_token REFRESH TOKEN which is to be revoked

Step 6: Calling An API

GET Used for retrieving resources.

POST Used for creating resources and performing

DELETE Used for deleting resources.

To get the details of a contact referred to by a speciﬁed salesorder_id

Responses will be in the JSON format.

Node Name Description

code Zoho Commerce error code. This will be zero

message Message for the invoked API.

resource name Comprises the invoked API’s Data.

All timestamps are returned in the ISO 8601 format - YYYY-MM-DDThh:mm:ssTZD.

HTTP Status Codes

Status Code Description

200 Success: The request was successfully

201 Created: The request was a success and one

400 Bad request: The request cannot be

401 Unauthorized (Invalid AuthToken): Request

404 URL Not Found: The URL you’ve sent is

405 Method Not Allowed: The requested

429 Too many requests: Too many requests

500 Server error: Zoho Commerce server

List all SalesOrders :

Retrieve a Sales Order :

Retrieves the details for an existing Sales Order.

conﬁrmed To mark salesorder as Conﬁrmed

void To mark salesorder as Declined

cancelled To mark salesorder as Cancelled

Add Sales Order Comments:

Use this API to add comments to your salesorder.

description string: The comment to be added

show_comment_to_client boolean: Boolean to determine whether the

mail_to_customer boolean: Boolean to determine whether it has

transaction_type string: Allowed values : salesorder,

Use this API to update addresses of your salesorder pizza.

billing To update the billing address