¶ Pending Sale
Pending sales are a great way to implement upsells and/or funnels in your e-commerce sales process. A pending sale allows you to have RevCent store a sale, including any related payment information, without immediately processing the payment. You can update the pending sale and process the payment at a later time. The pending sale functionality can be used via the API or the web app. For API users we highly recommend viewing our API documentation on pending sales.
¶ Why Use A Pending Sale?
- Store a customers' payment information, and cart information, for processing at a later time.
- Utilize pending sales with an upsell shopping cart flow, allowing you to update a sale before processing the final payment.
- Generate product recommendations for your upsells by using an Upsell Profile alongside a pending sale.
- Avoid upsell abandonment and rescue declined sales by automatically capturing a pending sale after a specific duration using a Pending Sale Profile.
¶ Related Information
- WooFunnels: Already using WooCommerce? Easily implement one click upsells using WooFunnels.
- Creating A Sale: For information on creating a sale, view the Create A Sale guide.
- Invoices: For information on invoices and creating an invoice, view the Invoice page.
- Upsell Profile: For information on RevCent's upsell profile features and capabilities for product recommendations, view the Upsell Profile page.
¶ Create A Pending Sale
Create a pending sale in the web app by Creating A Sale and selecting the “Pending” option for payment type. For detailed information on a pending sale and the RevCent API, view our API documentation.
¶ Pending Sale Flow
The below diagram details the pending sale flow. You first create a pending sale and use the initial unique_request_id as the reference ID for updates or to process payment on a specific pending sale.
¶ Pending Sale with Profiles
The below diagram details a pending sale request with both a Pending Sale Profile and an Upsell Profile implemented. When either profile types are created and enabled in your RevCent account, they are automatically implemented in sale requests. You can have a pending sale payment automatically processed after a set period of time using a Pending Sale Profile, have product recommendations returned in a pending sale request using an Upsell Profile, or both at the same time.
¶ Pending Sale V1 API Examples
Below is an example pending sale flow using the RevCent V1 API. If you are using the V2 API, please view the V2 API docs on pending sales.
¶ 1. Pending Sale Create
The pending sale is created with product, customer and payment information, all of which are stored in RevCent. However, the payment is not immediately processed due to the “is_pending”: true property. This allows you to implement any upsells or other funnel capabilities without saving the payment information locally.
API Request
{
"request": {
"type": "sale",
"method": "create",
"campaign": "Adwords Campaign",
"third_party_shop": "My RevCent Shop ID",
"iso_currency": "USD",
"is_pending": true,
"customer": {
"first_name": "vqjh",
"last_name": "slszhjru",
"address_line_1": "1600 Pennsylvania Ave",
"address_line_2": "",
"city": "Washington",
"state": "DC",
"zip": "20500",
"country": "USA",
"company": "",
"email": "ctnb@gmail.com",
"phone": "1234567890"
},
"payment": {
"credit_card": {
"card_number": "4242424242424242",
"exp_month": 4,
"exp_year": 22,
"card_code": "000"
},
"payment_type": "credit_card"
},
"product": [
{
"id": "robo_vac",
"quantity": 1
}
],
"unique_request_id": "mystorename_order_567"
}
}
- The “is_pending”: true property tells RevCent not to immediately process the payment. Required.
- RevCent creates a pending sale with product information, creates the new customer and saves the customers' payment information.
- You can include your own unique_request_id in the api request when creating a pending sale, i.e. a WooCommerce order ID, a UUID, etc. as the unique_request_id. If you do not include a unique_request_id in the initial request, RevCent will create one and provide it in the return response.
API Response
{
"amount": 34.99,
"api_call_id": "k6aGmwLkABi0822wnp67",
"api_call_processed": true,
"api_call_unix": 1613326956,
"campaign_id": "mJ1zZoOobEuP8pnWKXd1",
"campaign_name": "Adwords Campaign",
"code": 1,
"customer_id": "6rKPj6nlXACJRKKd5nXa",
"payment_type": "Credit Card",
"request_method": "create",
"request_type": "sale",
"result": "Pending sale created.",
"sale_id": "0pKnzNPq54U2yvvzJwVY",
"unique_request_id": "mystorename_order_567"
}
- RevCent will return the unique_request_id property which is to be used as a reference ID when updating or processing payment on the new pending sale.
- If you did not include a unique_request_id in the initial request RevCent will create one, otherwise the unique_request_id you provided is returned.
¶ 2. Pending Sale Update
You can update a pending sale, without processing the payment. This is useful in upsell scenarios when a customer picks an additional product to add, but is still shown more products further along the funnel. You can update a pending sale as many times as you want without processing payment.
API Request
{
"request": {
"type": "sale",
"method": "create",
"campaign": "Adwords Campaign",
"third_party_shop": "My RevCent Shop ID",
"is_pending": true,
"product": [
{
"id": "robo_vac",
"quantity": 1
},
{
"id": "av_2017",
"quantity": 1
}
],
"pending_options": {
"exists_options": {
"product": "replace",
"discount": "replace",
"shipping": "replace",
"tax": "replace"
}
},
"unique_request_id": "mystorename_order_567"
}
}
- In the example above, the customer added the av_2017 product to their cart during an upsell.
- The customer and payment information is not included as it has already been saved by RevCent.
- The unique_request_id is included in the update request to reference the same pending sale initially created. Required.
- The “is_pending”: true property tells RevCent not to immediately process the payment. Required.
- RevCent updates the pending sale with the new product line items according to the pending_options > exists_options settings > product = replace. Please read more about pending options in the 2A. Pending Options section below.
- Any shipping, tax or discounts included in the request would also replace existing entities in the pending sale.
API Response
{
"amount": 186.73,
"api_call_id": "X82JQZYRyqUqajGypN9l",
"api_call_processed": true,
"api_call_unix": 1613349181,
"campaign_id": "mJ1zZoOobEuP8pnWKXd1",
"campaign_name": "Adwords Campaign",
"code": 1,
"customer_id": "6rKPj6nlXACJRKKd5nXa",
"payment_type": "Credit Card",
"request_method": "create",
"request_type": "sale",
"result": "Pending sale updated.",
"sale_id": "0pKnzNPq54U2yvvzJwVY",
"unique_request_id": "mystorename_order_567"
}
- RevCent returns the updated pending sale, with the new amount reflecting the additional av_2017 product.
- The payment has still not been processed.
¶ 2A. Pending Options
There are options for updating existing items in a pending sale, specifically the pending_options > exists_options settings. These settings give you flexibility when updating a pending sales' existing product, shipping, tax and discount entities with any items present in the update request.
Example: You may want to add a product(s) to an existing pending sales' products, without modifying the existing pending sales' products. At the same time, you may wish to completely replace any shipping entities with those in the update request.
API Request Pending Options
"pending_options": {
"exists_options": {
"product": "replace | skip | merge_replace | merge_skip | merge_combine",
"discount": "replace | skip",
"shipping": "replace | skip",
"tax": "replace | skip"
}
},
¶ Exists Options
Exists options allow you to set rules for entities when updating the pending sale. Exists options apply to each request entity, in which to update the pending sale for existing entities. I.e. if updating a pending sale, what should RevCent do if an entity within the existing pending sale matches an entity contained in the update request.
¶ Product
What to do with product(s) submitted in the update in regards to product(s) already existing in the pending sale. I.e. Replace, skip, or merge line items already in a pending sale with line items submitted. Note: RevCent matches each product based on the "id" value submitted in the original request and update request.
- replace: Will remove all existing product(s) in the pending sale and replace with product(s) submitted in the request. I.e. Only product(s) submitted will be in the sale after update. (default)
- skip: Will leave existing product(s) in the sale and not add any new product(s) submitted. I.e. ignoring product(s) submitted. Useful when updating other parts of a pending sale such as payment information, discounts, etc.
- merge_replace: Will add any new product(s) to the pending sale, keep existing product(s) in the sale and replace existing same ID product(s) with product(s) submitted. I.e. When you want to update a pending sale with new product(s) not already in the sale, keep all existing product(s) but replace same ID existing product(s) with submitted product(s).
- merge_skip: Will add any new product(s) to the pending sale, and not remove or modify any product(s) which already exist in the sale. I.e. Add new product(s) to an existing sale without touching existing product(s).
- merge_combine: Will add any new product(s) to the pending sale, keep existing product(s) in the sale, and combine the quantities of existing product(s) with submitted same ID product(s). I.e. Add any new product(s) to the pending sale, keep existing product(s) in the sale and incrementing submitted quantity with same ID existing product(s) quantity.
¶ Shipping
The action to perform if shipping(s) already exists in a pending sale.
- replace: Will replace existing shipping with new shipping. (default)
- skip: Will skip if shipping exist.
¶ Tax
The action to perform if tax(s) already exists in a pending sale.
- replace: Will replace existing tax with new tax. (default)
- skip: Will skip if tax exists.
¶ Discount
The action to perform if discount(s) already exists in a pending sale.
- replace: Will replace existing discounts with new discounts. (default)
- skip: Will skip if discounts exist.
¶ 3. Pending Sale Process
When your sales funnel has concluded, and you are ready to process payment for the pending sale, you simply set the “is_pending” property to false. By setting the “is_pending” property to false, you are telling RevCent to process payment using the saved payment information.
API Request
{
"request": {
"type": "sale",
"method": "create",
"campaign": "Adwords Campaign",
"third_party_shop": "My RevCent Shop ID",
"payment_profile": "MyPaymentProfile",
"is_pending": false,
"unique_request_id": "mystorename_order_567"
}
}
- The unique_request_id is included in the process request to reference the same pending sale initially created. Required.
- The “is_pending”: false property tells RevCent to process the payment. Required.
- If implementing a third_party_shop, provide the RevCent ID for the shop. Optional.
- The payment_profile is provided to let RevCent know how to process the payment. Required if not providing third_party_shop, otherwise optional.
API Response
{
"amount": 26.74,
"amount_captured": 26.74,
"amount_discounted": 10,
"amount_fees": 0.59,
"amount_gross": 26.74,
"amount_net": 26.15,
"amount_original_total": 186.73,
"amount_remaining": 149.99,
"amount_to_salvage": 0,
"api_call_id": "O051ZWQ4XjijnV5LkVGl",
"api_call_processed": true,
"api_call_unix": 1565833755,
"campaign_id": "mJ1zZoOobEuP8pnWKXd1",
"campaign_name": "Adwords Campaign",
"card_id": "WmPn2g8bakcKnWWEmRlJ",
"code": 1,
"customer_id": "6rKPj6nlXACJRKKd5nXa",
"gateway": "Braintree",
"gateway_id": "NkAMJOzpB5iEAOrdloV0",
"product_sale_created": [
{
"amount_original_total": 149.99,
"amount_captured": 0,
"amount_gross": 0,
"amount_net": 0,
"amount_fees": 0,
"amount_remaining": 149.99,
"amount_to_salvage": 0,
"amount_discounted": 0,
"id": "7rwyAzL5LXUa8QrGMoMR",
"price": 149.99,
"quantity": 1,
"product": {
"id": "0pBLXVZW08SNw0XOKZ7X",
"name": "Robo Vac",
"internal_id": "robo_vac",
"sku": "robo_vac_sku"
},
"subscription": {
"id": "4r15qAlZlyUoMprMNVpE"
},
"trial": {
"id": "k6vn81lElqsvKEB4K2JA"
}
},
{
"amount_original_total": 19.99,
"amount_captured": 17.73,
"amount_gross": 17.73,
"amount_net": 17.25,
"amount_fees": 0.48,
"amount_remaining": 2.26,
"amount_to_salvage": 2.26,
"amount_discounted": 0,
"id": "Nk5vOzGAGRfrmg8LZXVM",
"price": 19.99,
"quantity": 1,
"product": {
"id": "6r8O5MLbw2t6n4v1lGqK",
"name": "AV 2017",
"internal_id": "av_2017",
"sku": "av_2017_sku"
},
"subscription": {
"id": "VPm9vVEoERc6Wy6Jg7Jg"
},
"trial": null
}
],
"request_method": "create",
"request_type": "sale",
"result": "Approved",
"sale_id": "rm9EG1BjrXcqm64KKq6z",
"transaction_id": "vEwWZv5B5zIXM9bq1yQd"
}
- RevCent returns the final sale result, indicating the pending sale is no longer pending, and has in fact been paid.
- All items created as a result of the sale are returned in the response. For more details on the sale response, view our API documentation.
¶ Pending Sale Profile
A pending sale profile in RevCent allows you to have RevCent automatically process a pending sale after a specified period of time. This is useful for declined sales, abandoned upsells, or in other situations where the customer abandoned a post purchase process.
¶ Why Use A Pending Sale Profile?
- Increase your revenue by processing abandoned or failed payments automatically.
- Process the payment for an abandoned upsell or other post purchase mechanism.
- Process a fully declined sale after a given period of time if the customer has not made a separate successful sale.
¶ View Pending Sale Profiles
View all pending sale profiles by clicking the Revenue > Sale > Pending Profiles link on the sidebar or going to https://revcent.com/user/pending-sale-profiles
¶ Create A Pending Sale Profile
Create a new pending sale profile by clicking the Create New Pending Sale Profile button when viewing all pending sale profiles or go to https://revcent.com/user/new-pending-sale-profile
¶ Name
Enter a name for the pending sale profile. Required and must be unique.
¶ Description
Enter a description for the pending sale profile.
¶ Status
Set the status of the pending sale profile.
- Click the Create New Pending Sale Profile button.
- Once the pending sale profile is created you will be forwarded to the Edit Pending Sale Profile page for the new pending sale profile. Please continue below.
¶ Edit A Pending Sale Profile
Edit an existing pending sale profile by clicking the edit button when viewing all pending sale profiles.
¶ Details
The pending sale profile details tab contains the basic fields.
¶ Name
Enter a name for the pending sale profile. Required and must be unique.
¶ Description
Enter a description for the pending sale profile.
¶ Status
Set the status of the pending sale profile.
¶ Auto Payment
The auto payment section is where you allow RevCent to automatically process pending sales, either unpaid or declined.
¶ Auto Payment Enabled
If you wish to have RevCent automatically process the payment for a pending sale after a given period of time. Auto payment only applies to credit card pending sales. Rules below are applied in order to prevent multiple sales for the same customer from being processed.
Auto Payment Restrictions:
- Any successful sale(s), for the same customer, created 24 hours prior to current pending sale will negate processing the current pending sale payment.
- Any sale(s) regardless of status, for the same customer, created after current pending sale will negate processing the current pending sale payment.
¶ Allow Unpaid Sales
If you wish to have RevCent automatically process the payment for a pending sale if it does not have any payment attempts. I.e. No transaction(s) were sent to a payment gateway. This applies to abandoned upsells or other post purchase mechanisms.
¶ Allow Declined Sales
If you wish to have RevCent automatically process the payment for a pending sale if it has unsuccessful payment attempts. I.e. Transaction(s) were sent to a payment gateway and were declined in full. No money collected. This applies to fully declined sales where you may wish to retry the sale on the customers' behalf after a specified period of time.
¶ Process Payment
The period of time to wait until RevCent automatically processes the pending sale payment. For example: After 1 day, after 6 hours, etc. Integer values only, decimals will be ignored.
¶ Payment Profile
Select an existing payment profile. RevCent must use a payment profile to process the auto payment.
¶ Apply To Settings
The apply to settings dictate when RevCent should use the pending sale profile, including specific source filters.
¶ Apply To Any Sale
Whether this profile should apply to any pending sale if the pending_sale_profile property is not present in the request.
- True: RevCent will apply the profile to any new pending sale.
- False: RevCent will only apply the profile to a request that contains the pending_sale_profile property in the request.
¶ Allowed Campaign(s)
Select one or more campaigns which are allowed to use the profile. If any selected, only the campaigns selected will be allowed to use this profile, disallowing non-selected campaigns. If none selected, all campaigns are allowed.
¶ Allowed Shop(s)
Select one or more shops which are allowed to use the profile. If any selected, only the shops selected will be allowed to use this profile, disallowing non-selected shops as well as requests not originating from a shop. If none selected, shops are not taken into consideration.
¶ Update Settings
The update settings contains details on what RevCent should do for specific scenarios when you are updating an existing pending sale that has not yet processed.
¶ Exists Options
Exists options are meant for users that intend to update an existing pending sale via API or shopping cart plugin and require custom rules. Exists options allow you to set rules for entities when updating the pending sale. Exists options apply to each request entity, in which to update the pending sale for existing entities. I.e. if updating a pending sale, what should RevCent do if an entity within the existing pending sale matches an entity contained in the update request.
¶ Product
What to do with product(s) submitted in the update in regards to product(s) already existing in the pending sale. I.e. Replace, skip, or merge line items already in a pending sale with line items submitted. Note: RevCent matches each product based on the "id" value submitted in the original request and update request.
- replace: Will remove all existing product(s) in the pending sale and replace with product(s) submitted in the request. I.e. Only product(s) submitted will be in the sale after update. (default)
- skip: Will leave existing product(s) in the sale and not add any new product(s) submitted. I.e. ignoring product(s) submitted. Useful when updating other parts of a pending sale such as payment information, discounts, etc.
- merge_replace: Will add any new product(s) to the pending sale, keep existing product(s) in the sale and replace existing same ID product(s) with product(s) submitted. I.e. When you want to update a pending sale with new product(s) not already in the sale, keep all existing product(s) but replace same ID existing product(s) with submitted product(s).
- merge_skip: Will add any new product(s) to the pending sale, and not remove or modify any product(s) which already exist in the sale. I.e. Add new product(s) to an existing sale without touching existing product(s).
- merge_combine: Will add any new product(s) to the pending sale, keep existing product(s) in the sale, and combine the quantities of existing product(s) with submitted same ID product(s). I.e. Add any new product(s) to the pending sale, keep existing product(s) in the sale and incrementing submitted quantity with same ID existing product(s) quantity.
¶ Shipping
The action to perform if shipping(s) already exists in a pending sale.
- replace: Will replace existing shipping with new shipping. (default)
- skip: Will skip if shipping exists.
¶ Tax
The action to perform if tax(s) already exists in a pending sale.
- replace: Will replace existing tax with new tax. (default)
- skip: Will skip if tax exists.
¶ Discount
The action to perform if discount(s) already exists in a pending sale.
- replace: Will replace existing discounts with new discounts. (default)
- skip: Will skip if discounts exist.