Place Order REST API Developer Guide
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 45
© Copyright 2000–2017 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc.,
as are other names and marks. Other marks appearing herein may be trademarks of their respective owners.
CONTENTS
Place Order REST API Developer Guide .....................................1
Requirements and Limitations ..............................................1
Understanding Authentication .............................................2
Defining Connected Apps ............................................3
Understanding OAuth Endpoints ........................................3
Understanding the Web Server OAuth Authentication Flow ......................4
Understanding the User-Agent OAuth Authentication Flow ......................9
Understanding the Username-Password OAuth Authentication Flow ...............12
Understanding the OAuth Refresh Token Process ............................15
Finding Additional Resources .........................................16
Understanding Place Order REST API Resources .................................17
Add a Contract and Orders to an Existing Account ...........................17
Add an Order to an Existing Account ....................................19
Add Orders to an Existing Contract .....................................20
Add Order Products to an Existing Order ..................................23
Get Details About a Contract ..........................................24
Get Details About an Order ..........................................26
Filter Details About a Contract .........................................27
Filter Details About an Order ..........................................28
Place Order REST API Resource Reference ....................................29
Create Contract-based Orders ........................................29
Contract-based Orders .............................................32
Create Order ....................................................35
Order .........................................................37
Index .............................................................41
PLACE ORDER REST API DEVELOPER GUIDE
Access your organization's order and contract data programmatically with the Salesforce Place Order REST API.
The Salesforce Place Order REST API is a composite API that gives programmatic access to contract, order, and order product data, as
well as child custom object data of contracts and orders in Salesforce. With this composite API, you can create contract, order, order
product, and custom object records in a single call. Any organization that has orders and API enabled can use the Place Order REST API.
Use the Place Order REST API, a REST-based composite application programming interface, to:
•Add orders to a new or existing contract, and add order products to those orders.
•Add order products to a new or existing order.
•Add custom objects to a new or existing contract or order.
•Retrieve order records under a given contract, plus those orders’ custom objects and order products.
•Retrieve order product records under a given order, plus custom object records under the order and its order products.
•Retrieve a filtered list of orders under a given contract or order products under a given order.
IN THIS SECTION:
Requirements and Limitations
Understanding Authentication
Salesforce uses the OAuth protocol to allow users of applications to securely access data without having to reveal username and
password credentials.
Understanding Place Order REST API Resources
Integrate your order creation system with Salesforce by using the Place Order REST API.
Place Order REST API Resource Reference
Each Place Order REST API resource is a URI used with an HTTP method (such as GET).
Requirements and Limitations
To access the Place Order REST API, you must establish a secure OAuth session ID.
Consider these limitations and general limits when using the Place Order REST API.
Limits and Limitations
•2000 records per request or the API maximum limit for your organization—whichever is lower.
•Responses and requests are in JSON.
When using Place Order REST API resources that require a request or response body, use Content-Type: application/json.
•Each call can only affect one top-level entity.
For orders under a contract, you need one call for each new or existing contract you’re adding orders, order products, or custom
objects to. For orders not under a contract, you need one call for each new or existing order you’re adding order products or
custom objects to.
•In each resource, you can create custom objects at a depth of one level below the top-level entity.
1
/services/data/latest API version/commerce/sale supports custom object records on contracts and
orders.
–
–/services/data/latest API version/commerce/sale/order supports custom object records on
orders and order products.
•Custom objects are not supported as children of other custom objects.
•To filter GET results, query parameters must be a fully qualified field name. The parent entity must be lower-cased (such as
order), and the field must match the defined relationship name (such as orders.StatusCode).
For example, to get a list of all orders with a draft status under a given contract, you must use
contract.orders.StatusCode='Draft'.
•When you create a new order, the Status Code must be Draft and the Status must be any value that corresponds to a
Status Code of Draft.
•You can’t update existing records.
Understanding Authentication
Salesforce uses the OAuth protocol to allow users of applications to securely access data without having to reveal username and password
credentials.
Before making REST API calls, you must authenticate the application user using OAuth 2.0. To do so, you’ll need to:
•Set up your application as a connected app in the Salesforce organization.
•Determine the correct Salesforce OAuth endpoint for your connected app to use.
•Authenticate the connected app user via one of several different OAuth 2.0 authentication flows. An OAuth authentication flow
defines a series of steps used to coordinate the authentication process between your application and Salesforce. Supported OAuth
flows include:
–Web server flow, where the server can securely protect the consumer secret.
–User-agent flow, used by applications that cannot securely store the consumer secret.
–Username-password flow, where the application has direct access to user credentials.
After successfully authenticating the connected app user with Salesforce, you’ll receive an access token which can be used to make
authenticated REST API calls.
IN THIS SECTION:
Defining Connected Apps
To authenticate using OAuth, you must create a connected app that defines your application’s OAuth settings for the Salesforce
organization.
Understanding OAuth Endpoints
OAuth endpoints are the URLs you use to make OAuth authentication requests to Salesforce.
Understanding the Web Server OAuth Authentication Flow
The web server authentication flow is used by apps that are hosted on a secure server. A critical aspect of the web server flow is that
the server must be able to protect the consumer secret. You can use code challenge and verifier values in the flow to prevent
authorization code interception.
2
Understanding AuthenticationPlace Order REST API Developer Guide
Understanding the User-Agent OAuth Authentication Flow
The user-agent authentication flow is used by client apps (consumers) that reside on the user’s device or computer. It’s also used
by client apps running in a browser using a scripting language such as JavaScript. These apps can protect per-user secrets. But,
because the apps are widely distributed, the client secret can’t be confidential.
Understanding the Username-Password OAuth Authentication Flow
Use the username-password authentication flow to authenticate when the consumer already has the user’s credentials.
Understanding the OAuth Refresh Token Process
The Web server OAuth authentication flow and user-agent flow both provide a refresh token that can be used to obtain a new access
token.
Finding Additional Resources
Defining Connected Apps
To authenticate using OAuth, you must create a connected app that defines your application’s OAuth settings for the Salesforce
organization.
When you develop an external application that needs to authenticate with Salesforce, you need to define it as a new connected app
within the Salesforce organization that informs Salesforce of this new authentication entry point.
Use the following steps to create a new connected app.
1. From Setup, enter Apps in the Quick Find box, then select Apps and click New in the Connected Apps section of the page
to start defining a connected app.
2. Enter the name of your application.
3. Enter the contact email information, as well as any other information appropriate for your application.
4. Select Enable OAuth Settings.
5. Enter a Callback URL. Depending on which OAuth flow you use, this is typically the URL that a user’s browser is redirected to
after successful authentication. As this URL is used for some OAuth flows to pass an access token, the URL must use secure HTTP
(HTTPS) or a custom URI scheme.
6. Add all supported OAuth scopes to Selected OAuth Scopes. These scopes refer to permissions given by the user running the
connected app.
7. Enter a URL for Info URL. This is where the user can go for more information about your application.
8. Click Save. The Consumer Key is created and displayed, and the Consumer Secret is created (click the link to reveal it).
Once you define a connected app, you use the consumer key and consumer secret to authenticate your application. See Creating a
Connected App in the Salesforce online help for specific steps to create a connected app for the type of authentication you need.
Understanding OAuth Endpoints
OAuth endpoints are the URLs you use to make OAuth authentication requests to Salesforce.
You need to use the correct Salesforce OAuth endpoint when issuing authentication requests in your application. The primary OAuth
endpoints are:
•For authorization: https://login.salesforce.com/services/oauth2/authorize
•For token requests: https://login.salesforce.com/services/oauth2/token
•For revoking OAuth tokens: https://login.salesforce.com/services/oauth2/revoke
3
Defining Connected AppsPlace Order REST API Developer Guide
All endpoints require secure HTTP (HTTPS). Each OAuth flow defines which endpoints you need to use and what request data you need
to provide.
If you’re verifying authentication on a sandbox organization, use “test.salesforce.com” instead of “login.salesforce.com” in all the OAuth
endpoints listed above.
Understanding the Web Server OAuth Authentication Flow
The web server authentication flow is used by apps that are hosted on a secure server. A critical aspect of the web server flow is that the
server must be able to protect the consumer secret. You can use code challenge and verifier values in the flow to prevent authorization
code interception.
In this flow, the client application requests the authorization server to redirect the user to another web server or resource that authorizes
the user and sends the application an authorization code. The application uses the authorization code to request an access token. The
following shows the steps for this flow.
1. The application redirects the user to the appropriate Salesforce authorization endpoint, such as
https://login.salesforce.com/services/oauth2/authorize. The following parameters are required:
DescriptionParameter
Must be code for this authentication flow.response_type
4
Understanding the Web Server OAuth Authentication FlowPlace Order REST API Developer Guide
DescriptionParameter
The Consumer Key from the connected app definition.client_id
The Callback URL from the connected app definition.redirect_uri
The following parameters are optional:
DescriptionParameter
Specifies the SHA256 hash value of the code_verifier
value in the token request to help prevent authorization code
code_challenge
interception attacks. The hash value must be base64url encoded
as defined here:
https://tools.ietf.org/html/rfc4648#section-5.
•If the code_challenge value is provided in the
authorization request and a code_verifier value is
provided in the token request, Salesforce compares the
code_challenge to the code_verifier. If the
code_challenge is invalid or doesn’t match, the login
fails with the invalid_request error code.
•If the code_challenge value is provided in the
authorization request, but a code_verifier value is
not provided in the token request, the login fails with the
invalid_grant error code.
Note: The value should be base64url-encoded only once.
Changes the login page’s display type. Valid values are:display
•page—Full-page authorization screen. This is the default
value if none is specified.
•popup—Compact dialog optimized for modern Web
browser popup windows.
•touch—Mobile-optimized dialog designed for modern
smartphones such as Android and iPhone.
•mobile—Mobile optimized dialog designed for
smartphones such as BlackBerry OS 5 that don’t support
touch screens.
Determines whether the user should be prompted for login and
approval. Values are either true or false. Default is false.
immediate
•If set to true, and if the user is currently logged in and has
previously approved the application, the approval step is
skipped.
•If set to true and the user is not logged in or has not
previously approved the application, the session is
5
Understanding the Web Server OAuth Authentication FlowPlace Order REST API Developer Guide
DescriptionParameter
immediately terminated with the
immediate_unsuccessful error code.
Provides a valid username value to pre-populate the login page
with the username. For
login_hint
example:login_hint=username@company.com. If a
user already has an active session in the browser, then the
login_hint parameter does nothing; the active user session
continues.
Specifies a value to be returned in the response; this is useful for
detecting "replay" attacks. Optional with the openid scope for
getting a user ID token.
nonce
Specifies how the authorization server prompts the user for
reauthentication and reapproval. This parameter is optional. The
only values Salesforce supports are:
prompt
•login—The authorization server must prompt the user for
reauthentication, forcing the user to log in again.
•consent—The authorization server must prompt the user
for reapproval before returning information to the client.
It is valid to pass both values, separated by a space, to require
the user to both log in and reauthorize. For example:
?prompt=login%20consent
Specifies what data your application can access. See “Scope
Parameter Values” in the online help for more information.
scope
Specifies any additional URL-encoded state data to be returned
in the callback URL after approval.
state
An example authorization URL might look something like the following:
https://login.salesforce.com/services/oauth2/authorize?response_type=code
&client_id=3MVG9lKcPoNINVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3X
HrXDiCQjK1mdgAvhCscA9GE&redirect_uri=https%3A%2F%2Fwww.mysite.com%2F
code_callback.jsp&state=mystate
2. The user logs into Salesforce with their credentials. The user is interacting with the authorization endpoint directly, so the application
never sees the user’s credentials. After successfully logging in, the user is asked to authorize the application. Note that if the user has
already authorized the application, this step is skipped.
3. After Salesforce confirms that the client application is authorized, the end-user’s Web browser is redirected to the callback URL
specified by the redirect_uri parameter. Salesforce appends authorization information to the redirect URL with the following
values:
6
Understanding the Web Server OAuth Authentication FlowPlace Order REST API Developer Guide
DescriptionParameters
Authorization code the consumer must use to obtain the access
and refresh tokens.
code
The state value that was passed in as part of the initial request,
if applicable.
state
An example callback URL with authorization information might look something like:
https://www.mysite.com/authcode_callback?code=aWekysIEeqM9PiT
hEfm0Cnr6MoLIfwWyRJcqOqHdF8f9INokharAS09ia7UNP6RiVScerfhc4w%3D%3D
4. The application extracts the authorization code and passes it in a request to Salesforce for an access token. This request is a POST
request sent to the appropriate Salesforce token request endpoint, such as
https://login.salesforce.com/services/oauth2/token. The following parameters are required:
DescriptionParameter
Value must be authorization_code for this flow.grant_type
The Consumer Secret from the connected app definition.
Required unless the Require Secret for Web
client_secret
Server Flow setting is not enabled in the connected app
definition.
The Consumer Key from the connected app definition.client_id
The Callback URL from the connected app definition.redirect_uri
Authorization code the consumer must use to obtain the access
and refresh tokens.
code
The following parameters are optional:
DescriptionParameter
Instead of passing in client_secret you can choose to
provide a client_assertion and
client_assertion
client_assertion_type. If a client_secret
parameter is not provided, Salesforce checks for the
client_assertion and client_assertion_type
automatically. The value of client_assertion must be a
typical JWT bearer token, signed with the private key associated
with the OAuth consumer’s uploaded certificate. Only the RS256
algorithm is currently supported. For more information on using
client_assertion, see the OpenID Connect specifications
for the private_key_jwt client authentication method.
7
Understanding the Web Server OAuth Authentication FlowPlace Order REST API Developer Guide
DescriptionParameter
Provide this value when using the client_assertion
parameter. The value of client_assertion_type must be
urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion_type
Specifies 128 bytes of random data with high enough entropy
to make it difficult to guess the value to help prevent
code_verifier
authorization code interception attacks. The value also must be
base64url encoded as defined here:
https://tools.ietf.org/html/rfc4648#section-5.
•If the code_verifier value is provided in the token
request and a code_challenge value is in the
authorization request, Salesforce compares the
code_verifier to the code_challenge. If the
code_verifier is invalid or doesn’t match, the login
fails with the invalid_grant error code.
•If the code_verifier value is provided in the token
request, but a code_challenge value was not provided
in the authorization request, the login fails with the
invalid_grant error code.
Note: The value should be base64url-encoded only once.
Expected return format. The default is json. Values are:format
•urlencoded
•json
•xml
The return format can also be specified in the header of the
request using one of the following:
•Accept:
application/x-www-form-urlencoded
•Accept: application/json
•Accept: application/xml
An example access token POST request might look something like:
POST /services/oauth2/token HTTP/1.1
Host: login.salesforce.com
grant_type=authorization_code&code=aPrxsmIEeqM9PiQroGEWx1UiMQd95_5JUZ
VEhsOFhS8EVvbfYBBJli2W5fn3zbo.8hojaNW_1g%3D%3D&client_id=3MVG9lKcPoNI
NVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCs
cA9GE&client_secret=1955279925675241571&
redirect_uri=https%3A%2F%2Fwww.mysite.com%2Fcode_callback.jsp
5. If this request is successful, the server returns a response body that contains the following:
8
Understanding the Web Server OAuth Authentication FlowPlace Order REST API Developer Guide
DescriptionParameters
Access token that acts as a session ID that the application uses
for making requests. This token should be protected as though
it were user credentials.
access_token
Token that can be used in the future to obtain new access tokens.refresh_token
Warning: This value is a secret. You should treat it like
the user's password and use appropriate measures to
protect it.
Identifies the Salesforce instance to which API calls should be
sent.
instance_url
Identity URL that can be used to both identify the user as well
as query for more information about the user. Can be used in an
HTTP request to get more information about the end user.
id
When the signature was created, represented as the number of
seconds since the Unix epoch (00:00:00 UTC on 1 January 1970).
issued_at
Base64-encoded HMAC-SHA256 signature signed with the
consumer's private key containing the concatenated ID and
signature
issued_at value. The signature can be used to verify
that the identity URL wasn’t modified because it was sent by the
server.
An example JSON response body might look something like:
{"id":"https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P",
"issued_at":"1278448101416",
"refresh_token":"5Aep8614iLM.Dq661ePDmPEgaAW9Oh_L3JKkDpB4xReb54_
pZebnUG0h6Sb4KUVDpNtWEofWM39yg==",
"instance_url":"https://yourInstance.salesforce.com/",
"signature":"CMJ4l+CCaPQiKjoOEwEig9H4wqhpuLSk4J2urAe+fVg=",
"access_token":"00Dx0000000BV7z!AR8AQP0jITN80ESEsj5EbaZTFG0R
NBaT1cyWk7TrqoDjoNIWQ2ME_sTZzBjfmOE6zMHq6y8PIW4eWze9JksNEkWUl.Cju7m4"}
6. The application uses the provided access token and refresh token to access protected user data.
Understanding the User-Agent OAuth Authentication Flow
The user-agent authentication flow is used by client apps (consumers) that reside on the user’s device or computer. It’s also used by
client apps running in a browser using a scripting language such as JavaScript. These apps can protect per-user secrets. But, because
the apps are widely distributed, the client secret can’t be confidential.
In this flow, the client application requests the authorization server to redirect the user to another Web server or resource which is capable
of extracting the access token and passing it back to the application. The following shows the steps for this flow.
9
Understanding the User-Agent OAuth Authentication FlowPlace Order REST API Developer Guide
1. The application redirects the user to the appropriate Salesforce authorization endpoint, such as
https://login.salesforce.com/services/oauth2/authorize. The following parameters are required:
DescriptionParameter
Must be token for this authentication flowresponse_type
The Consumer Key from the connected app definition.client_id
The Callback URL from the connected app definition.redirect_uri
The following parameters are optional:
DescriptionParameter
Changes the login page’s display type. Valid values are:display
•page—Full-page authorization screen. This is the default
value if none is specified.
•popup—Compact dialog optimized for modern Web
browser popup windows.
•touch—Mobile-optimized dialog designed for modern
smartphones such as Android and iPhone.
10
Understanding the User-Agent OAuth Authentication FlowPlace Order REST API Developer Guide
DescriptionParameter
•mobile—Mobile optimized dialog designed for
smartphones such as BlackBerry OS 5 that don’t support
touch screens.
Specifies what data your application can access. See “Scope
Parameter Values” in the online help for more information.
scope
Specifies any additional URL-encoded state data to be returned
in the callback URL after approval.
state
An example authorization URL might look something like the following:
https://login.salesforce.com/services/oauth2/authorize?response_type=token&
client_id=3MVG9lKcPoNINVBIPJjdw1J9LLJbP_pqwoJYyuisjQhr_LLurNDv7AgQvDTZwCoZuD
ZrXcPCmBv4o.8ds.5iE&redirect_uri=https%3A%2F%2Fwww.mysite.com%2Fuser_callback.jsp&
state=mystate
2. The user logs into Salesforce with their credentials. The user interacts with the authorization endpoint directly, so the application
never sees the user’s credentials.
3. Once authorization is granted, the authorization endpoint redirects the user to the redirect URL. This URL is defined in the remote
access application created for the application. Salesforce appends access token information to the redirect URL with the following
values:
DescriptionParameters
Access token that acts as a session ID that the application uses
for making requests. This token should be protected as though
it were user credentials.
access_token
Amount of time the access token is valid, in seconds.expires_in
Token that can be used in the future to obtain new access tokens.refresh_token
Warning: This value is a secret. You should treat it like
the user's password and use appropriate measures to
protect it.
The refresh token is only returned if the redirect URI is
https://login.salesforce.com/services/oauth2/success
or used with a custom protocol that is not HTTPS.
The state value that was passed in as part of the initial request,
if applicable.
state
Identifies the Salesforce instance to which API calls should be
sent.
instance_url
Identity URL that can be used to both identify the user as well
as query for more information about the user. Can be used in an
HTTP request to get more information about the end user.
id
11
Understanding the User-Agent OAuth Authentication FlowPlace Order REST API Developer Guide
DescriptionParameters
When the signature was created, represented as the number of
seconds since the Unix epoch (00:00:00 UTC on 1 January 1970).
issued_at
Base64-encoded HMAC-SHA256 signature signed with the
consumer's private key containing the concatenated ID and
signature
issued_at value. The signature can be used to verify
that the identity URL wasn’t modified because it was sent by the
server.
An example callback URL with access information appended after the hash sign (#) might look something like:
https://www.mysite.com/user_callback.jsp#access_token=00Dx0000000BV7z%21AR8
AQBM8J_xr9kLqmZIRyQxZgLcM4HVi41aGtW0qW3JCzf5xdTGGGSoVim8FfJkZEqxbjaFbberKGk
8v8AnYrvChG4qJbQo8&refresh_token=5Aep8614iLM.Dq661ePDmPEgaAW9Oh_L3JKkDpB4xR
eb54_pZfVti1dPEk8aimw4Hr9ne7VXXVSIQ%3D%3D&expires_in=7200&state=mystate
4. The application uses the provided access token and refresh token to access protected user data.
Keep the following considerations in mind when using the user-agent OAuth flow:
•Because the access token is encoded into the redirection URI, it might be exposed to the end-user and other applications residing
on the computer or device. If you’re authenticating using JavaScript, call window.location.replace(); to remove the
callback from the browser’s history.
Understanding the Username-Password OAuth Authentication Flow
Use the username-password authentication flow to authenticate when the consumer already has the user’s credentials.
In this flow, the user’s credentials are used by the application to request an access token as shown in the following steps.
Warning: This OAuth authentication flow passes the user’s credentials back and forth. Use this authentication flow only when
necessary. No refresh token is issued.
12
Understanding the Username-Password OAuth
Authentication Flow
Place Order REST API Developer Guide
1. The application uses the user’s username and password to request an access token. This is done via an out-of-band POST request
to the appropriate Salesforce token request endpoint, such as
https://login.salesforce.com/services/oauth2/token. These request fields are required:
DescriptionParameter
Must be password for this authentication flow.grant_type
The Consumer Key from the connected app definition.client_id
The Consumer Secret from the connected app definition.
Required unless the Require Secret for Web
client_secret
Server Flow setting is not enabled in the connected app
definition.
End-user’s username.username
End-user’s password.password
Note: You must append the user’s security token to their
password A security token is an automatically-generated
key from Salesforce. For example, if a user's password is
mypassword, and their security token is XXXXXXXXXX,
then the value provided for this parmeter must be
mypasswordXXXXXXXXXX. For more information on
13
Understanding the Username-Password OAuth
Authentication Flow
Place Order REST API Developer Guide
DescriptionParameter
security tokens see “Reset Your Security Token” in the
online help.
An example request body might look something like the following:
grant_type=password&client_id=3MVG9lKcPoNINVBIPJjdw1J9LLM82Hn
FVVX19KY1uA5mu0QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCscA9GE&client_secret=
1955279925675241571&username=testuser%40salesforce.com&password=mypassword123456
2. Salesforce verifies the user credentials, and if successful, sends a response to the application with the access token. This response
contains the following values:
DescriptionParameters
Access token that acts as a session ID that the application uses
for making requests. This token should be protected as though
it were user credentials.
access_token
Identifies the Salesforce instance to which API calls should be
sent.
instance_url
Identity URL that can be used to both identify the user as well
as query for more information about the user. Can be used in an
HTTP request to get more information about the end user.
id
When the signature was created, represented as the number of
seconds since the Unix epoch (00:00:00 UTC on 1 January 1970).
issued_at
Base64-encoded HMAC-SHA256 signature signed with the
consumer's private key containing the concatenated ID and
signature
issued_at value. The signature can be used to verify
that the identity URL wasn’t modified because it was sent by the
server.
An example response body might look something like:
{"id":"https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P",
"issued_at":"1278448832702","instance_url":"https://yourInstance.salesforce.com/",
"signature":"0CmxinZir53Yex7nE0TD+zMpvIWYGb/bdJh6XfOH6EQ=","access_token":
"00Dx0000000BV7z!AR8AQAxo9UfVkh8AlV0Gomt9Czx9LjHnSSpwBMmbRcgKFmxOtvxjTrKW1
9ye6PE3Ds1eQz3z8jr3W7_VbWmEu4Q8TVGSTHxs"}
3. The application uses the provided access token to access protected user data.
Keep the following considerations in mind when using the username-password OAuth flow:
•Since the user is never redirected to login at Salesforce in this flow, the user can’t directly authorize the application, so no refresh
tokens can be used. If your application requires refresh tokens, you should consider using the Web server or user-agent OAuth flow.
14
Understanding the Username-Password OAuth
Authentication Flow
Place Order REST API Developer Guide
Understanding the OAuth Refresh Token Process
The Web server OAuth authentication flow and user-agent flow both provide a refresh token that can be used to obtain a new access
token.
Access tokens have a limited lifetime specified by the session timeout in Salesforce. If an application uses an expired access token, a
“Session expired or invalid” error is returned. If the application is using the Web server or user-agent OAuth authentication flows, a refresh
token may be provided during authorization that can be used to get a new access token.
The client application obtains a new access token by sending a POST request to the token request endpoint with the following request
parameters:
DescriptionParameters
Value must be refresh_token.grant_type
The refresh token the client application already received.refresh_token
The Consumer Key from the connected app definition.client_id
The Consumer Secret from the connected app definition.
Required unless the Require Secret for Web Server
client_secret
Flow setting is not enabled in the connected app definition. This
parameter is optional.
Expected return format. The default is json. Values are:format
•urlencoded
•json
•xml
The return format can also be specified in the header of the request
using one of the following:
•Accept:
application/x-www-form-urlencoded
•Accept: application/json
•Accept: application/xml
This parameter is optional.
An example refresh token POST request might look something like:
POST /services/oauth2/token HTTP/1.1
Host: https://login.salesforce.com/
grant_type=refresh_token&client_id=3MVG9lKcPoNINVBIPJjdw1J9LLM82HnFVVX19KY1uA5mu0
QqEWhqKpoW3svG3XHrXDiCQjK1mdgAvhCscA9GE&client_secret=1955279925675241571
&refresh_token=your token here
Once Salesforce verifies the refresh token request, it sends a response to the application with the following response body parameters:
15
Understanding the OAuth Refresh Token ProcessPlace Order REST API Developer Guide
DescriptionParameters
Access token that acts as a session ID that the application uses for
making requests. This token should be protected as though it were
user credentials.
access_token
Identifies the Salesforce instance to which API calls should be sent.instance_url
Identity URL that can be used to both identify the user as well as
query for more information about the user. Can be used in an HTTP
request to get more information about the end user.
id
When the signature was created, represented as the number of
seconds since the Unix epoch (00:00:00 UTC on 1 January 1970).
issued_at
Base64-encoded HMAC-SHA256 signature signed with the
consumer's private key containing the concatenated ID and
signature
issued_at value. The signature can be used to verify that
the identity URL wasn’t modified because it was sent by the server.
An example JSON response body might look something like:
{ "id":"https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P",
"issued_at":"1278448384422","instance_url":"https://yourInstance.salesforce.com/",
"signature":"SSSbLO/gBhmmyNUvN18ODBDFYHzakxOMgqYtu+hDPsc=",
"access_token":"00Dx0000000BV7z!AR8AQP0jITN80ESEsj5EbaZTFG0RNBaT1cyWk7T
rqoDjoNIWQ2ME_sTZzBjfmOE6zMHq6y8PIW4eWze9JksNEkWUl.Cju7m4"}
Keep in mind the following considerations when using the refresh token OAuth process:
•The session timeout for an access token can be configured in Salesforce from Setup by entering Session Settings in the
Quick Find box, then selecting Session Settings.
•If the application uses the username-password OAuth authentication flow, no refresh token is issued, as the user cannot authorize
the application in this flow. If the access token expires, the application using username-password OAuth flow must re-authenticate
the user.
Finding Additional Resources
The following resources provide additional information about using OAuth with Salesforce:
•Authenticate Apps with OAuth
•Digging Deeper into OAuth on Force.com
•Using OAuth to Authorize External Applications
The following resources are examples of third party client libraries that implement OAuth that you might find useful:
•For Ruby on Rails: OmniAuth
•For Java: Apache Amber
•Additional OAuth client libraries: OAuth.net
16
Finding Additional ResourcesPlace Order REST API Developer Guide
Understanding Place Order REST API Resources
Integrate your order creation system with Salesforce by using the Place Order REST API.
Use this API to:
IN THIS SECTION:
Add a Contract and Orders to an Existing Account
Add an Order to an Existing Account
Add Orders to an Existing Contract
Add Order Products to an Existing Order
Get Details About a Contract
Get Details About an Order
Filter Details About a Contract
Filter Details About an Order
Add a Contract and Orders to an Existing Account
Here’s an example of a POST request using the Create Contract-based Orders resource to create a contract—with child orders, order
products, and custom objects—to an existing account.
Example usage
/services/data/v30.0/commerce/sale
Example request body
{
"contract": [
{
"attributes": {
"type": "Contract"
},
"AccountId": "001D000000JRDAv",
"StartDate": "2013-08-01",
"Status": "Draft",
"ContractTerm": "1",
"Test_Contract1__r": {
"records": [
{
"attributes": {
"type": "Test_Contract1__c"
},
"Name": "Contract Custom Object"
}
]
},
"Orders": {
"records": [
{
17
Understanding Place Order REST API ResourcesPlace Order REST API Developer Guide
"attributes": {
"type": "Order"
},
"EffectiveDate": "2013-08-11",
"Status": "Draft",
"billingCity": "SFO-Inside-OrderEntity-1",
"Pricebook2Id": "01sD0000000G2NjIAK",
"OrderItems": {
"records": [
{
"attributes": {
"type": "OrderItem"
},
"PricebookEntryId": "01uD0000001c5toIAA",
"quantity": "1",
"UnitPrice": "10"
}
]
}
}
]
}
}
]
}
Example JSON response body
{
"totalSize" : 1,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "Contract",
"url" : "/services/data/v30.0/sobjects/Contract/800D0000000PIcMIAW"
},
"Id" : "800D0000000PIcMIAW",
"Orders" : {
"totalSize" : 1,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "Order",
"url" : "/services/data/v30.0/sobjects/Order/801D0000000G0ylIAC"
},
"Id" : "801D0000000G0ylIAC",
"OrderItems" : {
"totalSize" : 1,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v30.0/sobjects/OrderItem/802D0000000CKoyIAG"
},
"Id" : "802D0000000CKoyIAG"
18
Add a Contract and Orders to an Existing AccountPlace Order REST API Developer Guide
} ]
}
} ]
},
"Test_Contract1__r" : {
"totalSize" : 1,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "Test_Contract1__c",
"url" : "/services/data/v30.0/sobjects/Test_Contract1__c/a02D0000006YYKZIA4"
},
"Id" : "a02D0000006YYKZIA4"
} ]
}
} ]
}
Add an Order to an Existing Account
Here’s an example of a POST request using the Create Order resource to create an order with order products for an existing account.
Example usage
/services/data/v30.0/commerce/sale/order
Example request body
{
"order": [
{
"attributes": {
"type": "Order"
},
"EffectiveDate": "2013-07-11",
"Status": "Draft",
"billingCity": "SFO-Inside-OrderEntity-1",
"accountId": "001D000000JRDAv",
"Pricebook2Id": "01sD0000000G2NjIAK",
"OrderItems": {
"records": [
{
"attributes": {
"type": "OrderItem"
},
"PricebookEntryId": "01uD0000001c5toIAA",
"quantity": "1",
"UnitPrice": "15.99"
}
]
}
}
]
}
19
Add an Order to an Existing AccountPlace Order REST API Developer Guide
Example JSON response body
{
"totalSize" : 1,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "Order",
"url" : "/services/data/v30.0/sobjects/Order/801D0000000G0ySIAS"
},
"Id" : "801D0000000G0ySIAS",
"OrderItems" : {
"totalSize" : 1,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v30.0/sobjects/OrderItem/802D0000000CKp8IAG"
},
"Id" : "802D0000000CKp8IAG"
} ]
}
} ]
}
Add Orders to an Existing Contract
Here’s an example of a PATCH request using the Contract-based Orders resource to add new orders and order products to an existing
contract.
Example usage
/services/data/v30.0/commerce/sale/800D0000000PFL8IAO
Example request body
{
"contract": [
{
"attributes": {
"type": "Contract"
},
"Id" : "800D0000000PFL8IAO",
"Orders": {
"records": [
{
"attributes": {
"type": "Order"
},
"EffectiveDate": "2013-08-11",
"Status": "Draft",
"billingCity": "SFO-Inside-OrderEntity-1",
"contractId": "800D0000000PFL8IAO",
"pricebook2Id": "01sD0000000G2JbIAK",
"OrderItems": {
20
Add Orders to an Existing ContractPlace Order REST API Developer Guide
"records": [
{
"attributes": {
"type": "OrderItem"
},
"PricebookEntryId": "01uD0000001c5tjIAA",
"quantity": "12",
"UnitPrice": "10"
},
{
"attributes": {
"type": "OrderItem"
},
"PricebookEntryId": "01uD0000001cAkMIAU",
"quantity": "2",
"UnitPrice": "20"
}
]
}
},
{
"attributes": {
"type": "Order"
},
"EffectiveDate": "2013-10-11",
"Status": "Draft",
"billingCity": "SFO-Inside-OrderEntity-1",
"contractId": "800D0000000PFL8IAO",
"pricebook2Id": "01sD0000000G2JbIAK",
"OrderItems": {
"records": [
{
"attributes": {
"type": "OrderItem"
},
"PricebookEntryId": "01uD0000001cAkRIAU",
"quantity": "11",
"UnitPrice": "10"
},
{
"attributes": {
"type": "OrderItem"
},
"PricebookEntryId": "01uD0000001cAkWIAU",
"quantity": "2",
"UnitPrice": "20"
},
{
"attributes": {
"type": "OrderItem"
},
"PricebookEntryId": "01uD0000001cAkgIAE",
"quantity": "14",
"UnitPrice": "10"
21
Add Orders to an Existing ContractPlace Order REST API Developer Guide
}
]
}
}
]
}
}
]
}
Example JSON response body
{
"totalSize" : 1,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "Contract"
},
"Orders" : {
"totalSize" : 2,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "Order",
"url" : "/services/data/v29.0/sobjects/Order/801D0000000G0xsIAC"
},
"Id" : "801D0000000G0xsIAC",
"OrderItems" : {
"totalSize" : 2,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v29.0/sobjects/OrderItem/802D0000000CKoPIAW"
},
"Id" : "802D0000000CKoPIAW"
}, {
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v29.0/sobjects/OrderItem/802D0000000CKoQIAW"
},
"Id" : "802D0000000CKoQIAW"
} ]
}
}, {
"attributes" : {
"type" : "Order",
"url" : "/services/data/v29.0/sobjects/Order/801D0000000G0xtIAC"
},
"Id" : "801D0000000G0xtIAC",
"OrderItems" : {
"totalSize" : 3,
"done" : true,
"records" : [ {
22
Add Orders to an Existing ContractPlace Order REST API Developer Guide
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v29.0/sobjects/OrderItem/802D0000000CKoRIAW"
},
"Id" : "802D0000000CKoRIAW"
}, {
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v29.0/sobjects/OrderItem/802D0000000CKoSIAW"
},
"Id" : "802D0000000CKoSIAW"
}, {
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v29.0/sobjects/OrderItem/802D0000000CKoTIAW"
},
"Id" : "802D0000000CKoTIAW"
} ]
}
} ]
}
} ]
}
Add Order Products to an Existing Order
Here’s an example of a PATCH request using the Order resource to add order products to an existing order.
Example usage
/services/data/v30.0/commerce/sale/order/801D0000000Frh8
Example request body
{
"order": [
{
"attributes": {
"type": "Order"
},
"Id":"801D0000000Frh8",
"OrderItems": {
"records": [
{
"attributes": {
"type": "OrderItem"
},
"PricebookEntryId": "01uD0000001cCd1",
"quantity": "1",
"UnitPrice": "100",
"orderId": "801D0000000Frh8"
},
{
"attributes": {
"type": "OrderItem"
23
Add Order Products to an Existing OrderPlace Order REST API Developer Guide
},
"PricebookEntryId": "01uD0000001cCd1",
"quantity": "2",
"UnitPrice": "200",
"orderId": "801D0000000Frh8"
}
]
}
}
]
}
Example JSON response body
{
"totalSize" : 1,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "Order"
},
"OrderItems" : {
"totalSize" : 2,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v30.0/sobjects/OrderItem/802D0000000CJtMIAW"
},
"Id" : "802D0000000CJtMIAW"
}, {
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v30.0/sobjects/OrderItem/802D0000000CJtNIAW"
},
"Id" : "802D0000000CJtNIAW"
} ]
}
} ]
}
Get Details About a Contract
Here’s an example of a GET request using the Contract-based Orders resource to query details about a contract and its child orders, order
products, and custom objects.
Example usage
/services/data/v30.0/commerce/sale/800D0000000PFHp
Example request body
None
24
Get Details About a ContractPlace Order REST API Developer Guide
Example JSON response body
{
"totalSize" : 1,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "Contract",
"url" : "/services/data/v30.0/sobjects/Contract/800D0000000PFHpIAO"
},
"Id" : "800D0000000PFHpIAO",
"Orders" : {
"totalSize" : 4,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "Order",
"url" : "/services/data/v30.0/sobjects/Order/801D0000000FqzsIAC"
},
"Id" : "801D0000000FqzsIAC",
"OrderItems" : {
"totalSize" : 3,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v30.0/sobjects/OrderItem/802D0000000CJX0IAO"
},
"Id" : "802D0000000CJX0IAO"
}, {
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v30.0/sobjects/OrderItem/802D0000000CJYDIA4"
},
"Id" : "802D0000000CJYDIA4"
}, {
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v30.0/sobjects/OrderItem/802D0000000CKFCIA4"
},
"Id" : "802D0000000CKFCIA4"
} ]
},
"Custom_Objects__r" : null
}, {
"attributes" : {
"type" : "Order",
"url" : "/services/data/v30.0/sobjects/Order/801D0000000FpNEIA0"
},
"Id" : "801D0000000FpNEIA0",
"OrderItems" : {
"totalSize" : 3,
"done" : true,
"records" : [ {
25
Get Details About a ContractPlace Order REST API Developer Guide
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v30.0/sobjects/OrderItem/802D0000000CIWBIA4"
},
"Id" : "802D0000000CIWBIA4"
}, {
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v30.0/sobjects/OrderItem/802D0000000CIWCIA4"
},
"Id" : "802D0000000CIWCIA4"
}, {
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v30.0/sobjects/OrderItem/802D0000000CIWDIA4"
},
"Id" : "802D0000000CIWDIA4"
} ]
},
"Custom_Objects__r" : null
}, {
"attributes" : {
"type" : "Order",
"url" : "/services/data/v30.0/sobjects/Order/801D0000000FqztIAC"
},
"Id" : "801D0000000FqztIAC",
"OrderItems" : null,
"Custom_Objects__r" : null
}, {
"attributes" : {
"type" : "Order",
"url" : "/services/data/v30.0/sobjects/Order/801D0000000FpkNIAS"
},
"Id" : "801D0000000FpkNIAS",
"OrderItems" : null,
"Custom_Objects__r" : null
} ]
},
"Test_Contract1__r" : null
} ]
}
Get Details About an Order
Here’s an example of a GET request using the Order resource to query details about an order and its order products and custom object
records.
Example usage
/services/data/v30.0/commerce/sale/order/801D0000000FzsM
Example request body
None
26
Get Details About an OrderPlace Order REST API Developer Guide
Example JSON response body
{
"totalSize" : 1,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "Order",
"url" : "/services/data/v30.0/sobjects/Order/801D0000000FzsMIAS"
},
"Id" : "801D0000000FzsMIAS",
"OrderItems" : {
"totalSize" : 2,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v30.0/sobjects/OrderItem/802D0000000CKIHIA4"
},
"Id" : "802D0000000CKIHIA4"
}, {
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v30.0/sobjects/OrderItem/802D0000000CKIGIA4"
},
"Id" : "802D0000000CKIGIA4"
} ]
},
"Custom_Objects__r" : null
} ]
}
Filter Details About a Contract
Here’s an example of a GET request using the Contract-based Orders resource to query a given contract’s activated orders.
Example usage
/services/data/v30.0/commerce/sale/800D0000000PFL8?contract.orders.StatusCode='Activated'
Example request body
None
Example JSON response body
{
"totalSize" : 1,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "Contract",
"url" : "/services/data/v30.0/sobjects/Contract/800D0000000PFHpIAO"
},
"Id" : "800D0000000PFHpIAO",
"Orders" : {
27
Filter Details About a ContractPlace Order REST API Developer Guide
"totalSize" : 1,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "Order",
"url" : "/services/data/v30.0/sobjects/Order/801D0000000FpNEIA0"
},
"Id" : "801D0000000FpNEIA0",
"OrderItems" : {
"totalSize" : 3,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v30.0/sobjects/OrderItem/802D0000000CIWBIA4"
},
"Id" : "802D0000000CIWBIA4"
}, {
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v30.0/sobjects/OrderItem/802D0000000CIWCIA4"
},
"Id" : "802D0000000CIWCIA4"
}, {
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v30.0/sobjects/OrderItem/802D0000000CIWDIA4"
},
"Id" : "802D0000000CIWDIA4"
} ]
},
"Custom_Objects__r" : null
} ]
},
"Test_Contract1__r" : null
} ]
}
Filter Details About an Order
Here’s an example of a GET request using the Order resource to query details for order products with a certain start date for a given order.
Example usage
/services/data/v30.0/commerce/sale/order/801D0000000FzsM?order.orderItems.effectivedate=2013-08-05
Example request body
None
Example JSON response body
{
"totalSize" : 1,
"done" : true,
"records" : [ {
28
Filter Details About an OrderPlace Order REST API Developer Guide
"attributes" : {
"type" : "Order",
"url" : "/services/data/v30.0/sobjects/Order/801D0000000FzsMIAS"
},
"Id" : "801D0000000FzsMIAS",
"OrderItems" : {
"totalSize" : 1,
"done" : true,
"records" : [ {
"attributes" : {
"type" : "OrderItem",
"url" : "/services/data/v30.0/sobjects/OrderItem/802D0000000CKIHIA4"
},
"Id" : "802D0000000CKIHIA4"
}]
},
"Custom_Objects__r" : null
} ]
}
Place Order REST API Resource Reference
Each Place Order REST API resource is a URI used with an HTTP method (such as GET).
Resources for the Place Order REST API are:
DescriptionSupported
HTTP Method
Resource
Add new orders, order products, and custom objects to
a new contract.
POST/services/data/latest API
version/commerce/sale
Add new orders, order products, and custom objects to
an existing contract. Retrieve a contract’s child orders,
order products, and custom objects.
PATCH, GET/services/data/latest API
version/commerce/sale/contract ID
Add new order products and custom objects to a new
order.
POST/services/data/latest API
version/commerce/sale/order
Add new order products and custom objects to an
existing order. Retrieve an order’s child order products
and custom objects.
PATCH, GET/services/data/latest API
version/commerce/sale/order/order ID
Create Contract-based Orders
With this resource, you can create a new contract with orders and order products, as well as custom object records on the contract or
order level.
29
Place Order REST API Resource ReferencePlace Order REST API Developer Guide
Syntax
URI
/services/data/latest API version/commerce/sale
Available since release
30.0
Formats
JSON
HTTP methods
POST
Request body
Since
Version
DescriptionTypeProperty
30.0Type and URL of the new contract.Attributesattributes
30.0Unique record identifier for the parent account.StringAccountId
30.0Status of the contract.StringStatus
30.0Child orders of the new contract.Orders[]Orders
30.0Child custom object records of the new contract.Custom
Objects[]
CustomObject__r
Attributes
Since
Version
DescriptionTypeProperty
30.0Format of the resource.Stringtype
Orders
Since
Version
DescriptionTypeProperty
30.0Type and URL of the new order record.Attributesattributes
30.0Status of the order.StringStatus
30.0Unique record identifier for the associated price book.StringPricebook2Id
30.0Child order products of the new order.Order Products[]OrderItems
30.0Child custom object records of the new order.Custom Objects[]CustomObject__r
30
Create Contract-based OrdersPlace Order REST API Developer Guide
Custom Object Records
Since
Version
DescriptionTypeProperty
30.0Type and URL of the custom object record.Attributesattributes
30.0Unique record identifier.StringId
Order Products
Since
Version
DescriptionTypeProperty
30.0Type and URL of the order product record.Attributesattributes
30.0Unique record identifier for the associated price book entry.StringPricebookEntryId
30.0Number of units of the order product.Numberquantity
30.0The unit price for the order product.CurrencyUnitPrice
Request parameters
None
Response body
DescriptionTypeProperty
Total number of records added.NumbertotalSize
When true, the operation was successful.Booleandone
Attributes and IDs of records.Records[]records
Records
DescriptionTypeProperty
Type and URL for the new record.Attributesattributes
Unique identifier for the new record.StringId
Attributes
DescriptionTypeProperty
Format of the resource.Stringtype
Resource URL.Stringurl
31
Create Contract-based OrdersPlace Order REST API Developer Guide
Example
See Add a Contract and Orders to an Existing Account on page 17.
Usage
You can only create one contract at a time. You can’t POST new orders onto an existing contract. For that, see the Contract-based Orders
resource.
Contract-based Orders
With this resource, you can add one or more new orders to an existing contract, as well as order products and custom object records
for each order, or you can retrieve data for a specific contract.
If available, GET method retrieves the contract’s child orders and order products, as well as custom objects under the contract and orders.
Syntax
URI
/services/data/latest API version/commerce/sale/contractId
For retrieving filtered data:
/services/data/latest API version/commerce/sale/contract ID?contract.orders.field
name=value
Available since release
30.0
Formats
JSON
HTTP methods
PATCH, GET
Request parameters
•You can use parameters for all standard and custom fields on contracts, orders, order products, and any custom objects directly
related to these objects.
•The parameters must be fully qualified. For example: objectname.relationshipname.fieldname=value.
–Object name must be all lower-case.
–Relationship name must match what is defined on the object and is case-sensitive.
–Field name isn’t case sensitive.
–If the value is a string, it must be encased in single quotation marks. If the value is a number, it must not be encased. If the
value is a date, it should be in the YYYY-MM-DD format.
•You can use multiple parameter fields, separated by "&", to make more detailed filters. For example:
/services/data/v30.0/commerce/sale/{contractId}?contract.status='Activated'
&contract.Orders.status='Draft'&contract.Orders.OrderItems.unitprice=300
The following aren’t supported:
32
Contract-based OrdersPlace Order REST API Developer Guide
•Arrays of values. For example: contract.orders.Status='Activated','Draft'.
•Operators: >, >=, < and <=
•The OR condition
Since
Version
DescriptionParameters
30.0The object name of the record being filtered. In this resource, this is always
contract.
contract
30.0The relationship name of the field that the order’s data will be filtered by.
In this resource, this is always orders.
orders
30.0The field whose value to filter by. For example, if you want to only retrieve
orders with a status category, the field name is StatusCode.
field name
30.0The value to filter by. For example, if you want to only retrieve orders
with a status category of Activated, the value is Activated.
value
Request body
Since
Version
DescriptionTypeProperty
30.0Type of the contract.Attributesattributes
30.0Unique contract identifier.StringId
30.0Child orders of the contract.Orders[]Orders
Attributes
Since
Version
DescriptionTypeProperty
30.0Format of the resource.Stringtype
Order Records
Since
Version
DescriptionTypeProperty
30.0Type of the order record.Attributesattributes
30.0Status of the order.StringStatus
30.0Unique record identifier for the parent contract.StringcontractId
30.0Unique record identifier for the associated price book.Stringpricebook2Id
30.0Child order products of the order.Order Products[]OrderItems
33
Contract-based OrdersPlace Order REST API Developer Guide
Since
Version
DescriptionTypeProperty
30.0Child custom object records of the order.Custom
Objects[]
CustomObject__r
Order Products
Since
Version
DescriptionTypeProperty
30.0Type and URL of the order product.Attributesattributes
30.0Unique record identifier for the associated price book entry.StringPricebookEntryId
30.0Number of units of the order product.Numberquantity
30.0The unit price for the order product.CurrencyUnitPrice
Custom Objects
Since
Version
DescriptionTypeProperty
30.0Type and URL of the custom object.Attributesattributes
30.0Unique custom object identifier.StringId
Response body
DescriptionTypeProperty
Total number of records retrieved.NumbertotalSize
When true, the operation was successful.Booleandone
Attributes and ID of contract record.Records[]records
Records
DescriptionTypeProperty
Type and URL of the record.Attributesattributes
Unique contract identifier.StringId
34
Contract-based OrdersPlace Order REST API Developer Guide
Attributes
DescriptionTypeProperty
Format of the resource.Stringtype
Resource URL.Stringurl
Examples
•Add Orders to an Existing Contract on page 20
•Get Details About a Contract on page 24
•Filter Details About a Contract on page 27
Create Order
With this resource, you can create a new order with order products and custom objects.
If you don’t want to add the order to a contract, you can add it directly to an account. You can only create one new order per call. The
request body must have either an account or a contract as its parent record, and it must have a reference to a price book.
Syntax
URI
/services/data/latest API version/commerce/sale/order
Available since release
30.0
Formats
JSON
HTTP methods
POST
Request body
Since
Version
DescriptionTypeProperty
30.0Type and URL of the new order.Attributesattributes
30.0Child order products of the new order.Order Products[]OrderItems
30.0Child custom object records of the new order.Custom Objects[]CustomObject__r
35
Create OrderPlace Order REST API Developer Guide
Attributes
Since
Version
DescriptionTypeProperty
30.0Format of the resource.Stringtype
30.0Resource URL.Stringurl
Order Products
Since
Version
DescriptionTypeProperty
30.0Type and URL of the order product.Attributesattributes
30.0Unique record identifier for the associated price book entry.StringPricebookEntryId
30.0Number of units of the order product.Numberquantity
30.0The unit price for the order product.CurrencyUnitPrice
30.0Unique order product identifier.StringId
Custom Objects
Since
Version
DescriptionTypeProperty
30.0Type and URL of the custom object.Attributesattributes
30.0Unique custom object identifier.StringId
Request parameters
None
Response body
DescriptionTypeProperty
Total number of records retrieved.NumbertotalSize
When true, the operation was successful.Booleandone
Attributes and ID of contract record.Records[]records
36
Create OrderPlace Order REST API Developer Guide
Records
DescriptionTypeProperty
Type and URL of the record.Attributes on page
37
attributes
Unique contract identifier.StringId
Attributes
DescriptionTypeProperty
Format of the resource.Stringtype
Resource URL.Stringurl
Example
See Add an Order to an Existing Account on page 19.
Order
Use this resource to add one or more new order products and custom object records to an existing order or to retrieve data for a specific
order.
You can only PATCH one order at a time.
If available, GET method retrieves the orders’ child order products and custom objects under the order or order products.
Syntax
URI
/services/data/latest API version/commerce/sale/order/order ID
For retrieving filtered data:
/services/data/latest API version/commerce/sale/order/order ID?order.orderItems.field
name=value
Available since release
30.0
Formats
JSON
HTTP methods
POST
37
OrderPlace Order REST API Developer Guide
Request body
Since
Version
DescriptionTypeProperty
30.0Type and URL of the order.Attributesattributes
30.0Child order products of the new order.Order
Products
OrderItems
30.0Child custom object records of the new order.Custom
Object
CustomObject__r
Attributes
Since
Version
DescriptionTypeProperty
30.0Format of the resource.Stringtype
Order Products
Since
Version
DescriptionTypeProperty
30.0Type and URL of the order product.Attributesattributes
30.0Unique record identifier for the associated price book entry.StringPricebookEntryId
30.0Number of units of the order product.Numberquantity
30.0The unit price for the order product.CurrencyUnitPrice
30.0Unique record identifier for the parent order.StringorderId
30.0Unique order product identifier.StringId
Custom Objects
Since
Version
DescriptionTypeProperty
30.0Type and URL of the custom object.Attributesattributes
30.0Unique custom object identifier.StringId
Request parameters
•You can use parameters for all standard and custom fields on contracts, orders, order products, and any custom objects directly
related to these objects.
•The parameters must be fully qualified. For example: objectname.relationshipname.fieldname=value.
38
OrderPlace Order REST API Developer Guide
Object name must be all lower-case.
–
–Relationship name must match what is defined on the object and is case-sensitive.
–Field name isn’t case sensitive.
–If the value is a string, it must be encased in single quotation marks. If the value is a number, it must not be encased. If the
value is a date, it should be in the YYYY-MM-DD format.
•You can use multiple parameter fields, separated by "&", to make more detailed filters. For example:
/services/data/v30.0/commerce/sale/{contractId}?contract.status='Activated'
&contract.Orders.status='Draft'&contract.Orders.OrderItems.unitprice=300
The following aren’t supported.
•Arrays of values. For example: order.orderItems.effectiveDate=2013–01–01,2013–01–02.
•Operators: >, >=, < and <=
•The OR condition
DescriptionParameters
The object name of the record being filtered. In this resource,
this is always order.
order
The relationship name of the field that the order’s data will be
filtered by. In this resource, this is always orderItems.
orderItems
The field whose value to filter by. For example, if you want to
only retrieve order products with a certain start date, the field
name is effectivedate.
field name
The value to filter by. For example, if you want to only retrieve
order products that started on January 1, 2013, the value is
2013–01–01.
value
Response body
DescriptionTypeProperty
Total number of records listed.NumbertotalSize
Attributes and IDs of the new records.Records[]records
Records
DescriptionTypeProperty
Type and URL for the record.Attributesattributes
Unique record identifier.StringId
39
OrderPlace Order REST API Developer Guide
INDEX
A
Add order products
on existing order 23
Authentication
Additional resources 16
OAuth 2–4, 9, 12, 15
OAuth endpoints 3
Remote access applications 3
G
Get contract data
filtered 27
unfiltered 24
Get order data
filtered 28
unfiltered 26
I
Introduction 1
L
Limitations 1
Limits, general 1
O
OAuth
Additional resources 16
Refresh token 15
User-agent OAuth flow 9
Username-password OAuth flow 12
Web server OAuth flow 4
P
Place order with order products
on existing account 19
on existing contract 20
on new contract 17
standalone 19
R
Reference 29
Requirements 1
Resource
GET data for an order 37
GET filtered data for an order 37
PATCH custom object, on existing order 37
PATCH custom object, on new order product 37
PATCH existing order 37
PATCH order products, on existing order 37
Resources
examples 17
GET data for a contract 32
GET filtered data for a contract 32
PATCH custom object, on existing contract 32
PATCH custom object, on new order 32
PATCH existing contract 32
PATCH orders and order products, on existing contract 32
POST an order 35
POST contract 29
POST custom object records, on contract-based orders 29
POST custom object records, on new contract 29
POST custom object records, on new order 35
POST custom object records, on new order products 35
POST order products, on new contract-based orders 29
POST order products, on new order 35
POST orders, on new contract 29
41
