Price Agreements Integration Guide

DOCS

Last updated: Sept 23rd, 5:29pm

The Price Agreements API is a PayPal limited release REST API that you can use in conjunction with other publicly available external APIs.

PayPal merchants might use the Price Agreement API with a customer relationship management (CRM) tool, back-end pricing engine, and a price optimization tool to assess the profitability of a pricing request, as follows:

A merchant uses a CRM tool to create a price agreement. The CRM tool calls the API to create the agreement.

The API connects with a back-end pricing engine and price optimization tool to assess the profitability of the request.

You can also use the Price Agreement API to revise, delete, update, and submit price agreements.

Endpoints

To create an API request, combine either of these endpoints with other URI components:


Live	`https://api-m.paypal.com`
Sandbox	`https://api-m.sandbox.paypal.com`

URI components

To create the endpoint URI to make API requests, combine an endpoint with these HTTP methods and API resources:

Method	Resource	API request	Inputs
`POST`	`<endpoint>/v1/pricing/agreements`	Creates a price agreement	JSON request body
`PUT`	`<endpoint>/v1/pricing/agreements/<id>`	Updates a price agreement	ID and JSON request body
`DELETE`	`<endpoint>/v1/pricing/agreements/<id>`	Deletes a price agreement	ID
`POST`	`<endpoint>/v1/pricing/agreements/<id>/submit`	Submits a price agreement	ID
`POST`	`<endpoint>/v1/pricing/agreements/<id>/revise`	Revises a price agreement	ID and JSON request body

For example, to show details for a price agreement in the sandbox, use the following cURL command:

1curl -v -X GET https://api-m.sandbox.paypal.com/v1/pricing/agreements/PA-00008712-1 \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer <Access-Token>"

Integration steps

After a customer relationship management (CRM) app, such as Salesforce, receives pricing requests from merchants, you can use the Price Agreements API to complete this typical task flow to assess pricing requests for PayPal merchants:


1.	Required	Set up your development environment.
2.	Required	Create a price agreement for the merchants. Use the API or a CRM app that calls the API.
3.	Optional	After the sales users review the results and amend the pricing request, update the price agreement based on the posted analysis. Use the API or a CRM app that calls the API.
4.	Required	If all approvals are complete, submit the price agreement. Use the API or a CRM app that calls the API.
5.	Optional	If the inputs must be updated after the price agreement goes through approvals, revise the price agreement. Use the API or a CRM app that calls the API. For example, this action might create a new version of the agreement internally and return a revised agreement.
6.	Optional	If any disapprovals occur for the agreement, delete the price agreement. The delete operation completes a soft delete. Use the API or your CRM app. You can update your pricing tool to maintain a record for tracking purposes.

Set up your development environment

Before you can integrate Price Agreements, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get started.

Then, return to this page to integrate Price Agreements.

Create price agreement

To create a price agreement, specify details about the merchant, price agreement, and product line items in the JSON request body:

Agreement details

Parameter	Data type	Description
`business_region`	`string`	Required. The region or geography of the merchant.
`global_merchant`	`object`	Required. The global merchant details for this deal.
`effective_date`	`string`	Required. The date and time when the deal goes into effect for the merchant, in Internet date and time format.
`live_to_site_date`	`string`	Required. The date and time when the merchant goes live with this price change, in Internet date and time format.
`validity_from`	`string`	Required. The date and time when the deal became valid, in Internet date and time format.
`validity_to`	`string`	Required. The date and time after which the deal is no longer valid, in Internet date and time format.
`pricing_currency`	`string`	Required. The three-character ISO-4217 currency code of the primary currency for the agreement.
`volume_tiers`	`object`	The details about volume tiers, if applicable.
`average_selling_price_tiers`	`array` of  `asp_tier` objects	An array of details about average selling price (ASP) tiers for a deal at either a line item or volume tiers level, if applicable. Different prices are offered for different average selling transaction prices.
`agreement_price_points`	`object`	The price points that are common to all products that are priced as part of this request.
`line_items`	`array` of  `line_item` objects	Required. An array of line items, or products, that are priced in the agreement. Each product has a line item.

A successful request returns the ID for the new agreement, price agreement details, and HATEOAS links that enable you to complete tasks against the agreement. For details, see create price agreement.

Next, you can optionally update the price agreement.

Update price agreement

After the sales users review the results and amend the pricing request, you can update the price agreement based on the posted analysis.

Note: Use the update operation enables you to modify an agreement that is in draft state. To update an approved agreement, you must revise a price agreement.

To update a price agreement, specify the agreement ID in the URI and agreement details in the JSON request body. A successful request returns the HTTP 200 OK status code and a JSON response body that shows price agreement details.

For details, see update price agreement.

Next, you can submit the price agreement.

Submit price agreement

If all approvals are complete, you can submit the price agreement. To submit an agreement, specify the agreement ID and the submit action in the URI. A successful request returns the HTTP 204 No Content status code with no JSON response body.

For details, see submit price agreement.

Next, you can optionally revise the price agreement.

Revise price agreement

If the inputs must be updated after the price agreement goes through approvals, you can revise the price agreement.

To revise a price agreement, specify the agreement ID and the revise action in the URI. In the JSON request body, specify the agreement details information to revise. A successful request returns the HTTP 201 Created status code and a JSON response body that shows price agreement details.

For details, see revise price agreement.

Next, you can optionally delete the price agreement.

Delete price agreement

The delete operation completes a soft delete. You can maintain a record within your pricing tool for tracking purposes. To delete a price agreement, specify the agreement ID in the URI. A successful request returns the HTTP 204 No Content status code with no JSON response body.

For details, see delete price agreement.

Additional information

Price Agreements API reference