Order Placement and Management FAQ

Updated October 25, 2023 14:55

This Article Contains The Following Questions:

How does Ordergroove securely place orders?
How does Ordergroove communicate discounts in the order XML?
How should my system identify an incoming order from Ordergroove?
What does "connection error during placement" mean?
What does “exception error during placement preparation” mean?
What does “pending placement” mean?
Why is this old order still in “pending placement”?
Why aren't orders placing?
Out of Stock (OOS) FAQ

Q: How does Ordergroove securely place orders for each app/cartridge?

Ordergroove has two options for placing recurring orders to an endpoint with authentication. You’ll find examples of both below. Our SFCC cartridge and Shopify app use the Authentication header with order placement API requests.

Authentication Header
Shopify, SFCC, BigCommerce, Custom
Using this order placement authentication will result in a JSON Authorization Header getting sent along with the order XML.

public_id	The public ID of the merchant in Ordergroove’s database
ts	Timestamp (seconds since epoch) - auth expires in 2 hours
sig_field	The customer ID in the merchant’s database
sig	HMAC generated signature using the secret hash key provided by OG

{"public_id":"2d4f8be6995c11e7a3eebc764e106cf4","ts":"1595433856","sig_field":"698008","sig":"ae1pGy7LBtZFyeQtL0jUe6be4MWXcsAw6tUO2Z7Si5U="}

Basic Authentication
Custom, Legacy SFCC, Legacy Magento
If you want to use basic authentication, Ordergroove can pass a username and password in the body of the request.

username=afakeusername&xml=<?xml version="1.0" encoding="UTF-8"?>
<order>
...
</order>
&password=afakepassword

Token Authentication
Big Commerce (Legacy)
For this authentication, Ordergroove uses a JWT token to place the order to our Big Commerce application, and the application authorizes it directly with the Big Commerce checkout API.

Content-Type: application/xml
Authorization-Client: f735aaf2a1ac11ea97f3bc764e10b970
Authorization: eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJpc3MiOiAiYmMtb2ctbWlkZGxld2FyZSIsICJpYXQiOiAxNjA0MzM0MDk0LCAiZXhwIjogMTYwNDM0MTI5NCwgImF1ZCI6ICJPcmRlckdyb292ZSIsICJzdWIiOiAiZjczNWFhZjJhMWFjMTFlYTk3ZjNiYzc2NGUxMGI5NzAifQ.CdjcSXmrETlD4ssoP2PTsJXXgTnTixvlUkDH9Eul-sU

Q: How Does Ordergroove Communicate Discounts In The Order XML?

When your customers' recurring orders place, Ordergroove will send an Order XML to your API order placement endpoint for each individual order to be ingested into your Order Management System. The Order XML will include customer and product details for you to fulfill the order.

Within the Order XML, Ordergroove will apply the applicable incentive at the product line item level, not the overall order level. OG will pass the discounted price multiplied by the quantity in the finalPrice field of the Order XML, nested under items. To charge the customer, you must use this price field as the final price, and no additional calculation is needed by your Order Management System. Ordergroove will use the pricing provided in the product feed to determine the price sent during order placement. This price will be locked in ten days prior to the order being placed.

Shipping Fees

If the customer is receiving free shipping, Ordergroove will pass $0 as the shipping cost in the order XML. If you have a flat rate shipping fee applied, that will also be passed within the Order XML. Ordergroove does not accommodate dynamic shipping rates — only a flat rate.

Sample Order XML

<?xml version="1.0" encoding="UTF-8"?>
 <order> 
 <head>
 <orderOgId>9507</orderOgId> // The order ID within OrderGroove
 <orderOgDate><![CDATA[2010-08-12]]></orderOgDate> // Date the order was placed
 <orderSourcePartnerId>123</orderSourcePartnerId>
 <orderSourcePartnerName><![CDATA[OrderGroove]]></orderSourcePartnerName>
 <orderSubtotalValue>112.42</orderSubtotalValue> // Each item's Final Price added together (already includes the discount)
 <orderSalesTax>0.00</orderSalesTax> // Tax will always be calculated downstream of OG
 <orderShipping>1.99</orderShipping> // Will only populate a flat rate if set of 0.00
 <orderTotalValue>114.41</orderTotalValue> // SubtotalValue + Shipping
 <orderCcType>Visa</orderCcType> // Visa/Mastercard/American Express/Discover
 <orderCcOwner><![CDATA[EVosArcIjFgb30mtSw==]]></orderCcOwner> // AES Encrypted- Will only populate if passed within the purchasePOST
 <orderCcNumber><![CDATA[bwRvVOMZ+BpJgRr9CCKk4Q==]]></orderCcNumber> // AES Encrypted- Will only populate if passed within the purchasePOST
 <orderCcExpire><![CDATA[awZxV+IZ+A==]]></orderCcExpire> // AES Encrypted- Will only populate if passed within the purchasePOST
 </head>
 <customer>
 <customerOgId>1638</customerOgId> // Customer ID within OrderGroove
 <customerPartnerId><![CDATA[1000046]]></customerPartnerId> // Customer ID within merchant system
 <customerName><![CDATA[Andrew Magne]]></customerName>
 <customerFirstName><![CDATA[Andrew]]></customerFirstName>
 <customerLastName><![CDATA[Magne]]></customerLastName>
 <customerEmail><![CDATA[andrew@ordergroove.com]]></customerEmail> // Billing Fields will only populate if passed within the purchasePOST
 <customerBillingFirstName><![CDATA[Andrew]]></customerBillingFirstName>
 <customerBillingLastName><![CDATA[Magne]]></customerBillingLastName>
 <customerBillingAddress><![CDATA[900 Broadway Suite 402]]></customerBillingAddress>
 <customerBillingAddress1><![CDATA[900 Broadway]]></customerBillingAddress1>
 <customerBillingAddress2><![CDATA[Suite 402]]></customerBillingAddress2>
 <customerBillingCity><![CDATA[New York]]></customerBillingCity>
 <customerBillingState><![CDATA[NY]]></customerBillingState>
 <customerBillingZip><![CDATA[10011]]></customerBillingZip>
 <customerBillingPhone><![CDATA[]]></customerBillingPhone>
 <customerBillingFax><![CDATA[]]></customerBillingFax>
 <customerBillingCompany><![CDATA[]]></customerBillingCompany>
 <customerBillingCountry><![CDATA[US]]></customerBillingCountry>
 <customerShippingFirstName><![CDATA[Andrew]]></customerShippingFirstName>
 <customerShippingLastName><![CDATA[Magne]]></customerShippingLastName>
 <customerShippingAddress><![CDATA[56 110 St Apt "B"]]></customerShippingAddress>
 <customerShippingAddress1><![CDATA[56 110 St]]></customerShippingAddress1>
 <customerShippingAddress2><![CDATA[Apt "B"]]></customerShippingAddress2>
 <customerShippingCity><![CDATA[Astoria]]></customerShippingCity>
 <customerShippingState><![CDATA[NY]]></customerShippingState>
 <customerShippingZip><![CDATA[11333]]></customerShippingZip>
 <customerShippingPhone><![CDATA[718-555-9048]]></customerShippingPhone>
 <customerShippingFax><![CDATA[]]></customerShippingFax>
 <customerShippingCompany><![CDATA[]]></customerShippingCompany>
 <customerShippingCountry><![CDATA[US]]></customerShippingCountry>
 </customer>
 <items>
 <item>
 <qty>1</qty>
 <product_id><![CDATA[1109]]></product_id> // Product ID within merchant system
 <discount>2.45</discount> // Program-wide product discount
 <finalPrice>37.00</finalPrice> // (Price * Quantity) - Price merchant charges customer
 </item>
 </items>
 </order>

Q: How should my system identify an incoming order from Ordergroove?

If you are using an API for order placement, and it is being used exclusively by Ordergroove, you can add an identifier to all orders that come in via that endpoint.

Shopify will append a flag to the order to identify it as an Ordergroove order.

Q: What does “connection error during placement” mean?

(Applicable to API order placement merchants only.) Ordergroove was unable to connect with your order placement endpoint, which returned a 400 level response code, triggering an indefinite retry. This could be the result of a number of conditions:

The service was experiencing temporary downtime or server maintenance.
Authentication changed on the order placement endpoint.
Your order placement endpoint changed and the new endpoint is not yet configured on the Ordergroove side.
An order processing error has been incorrectly mapped to a 400 level response.
Your integration is in an early phase and your endpoint is not yet set up and ready to receive API requests.

Q: What does “exception error during placement preparation” mean?

Orders in this status have usually experienced a technical glitch or data issue — like a missing or corrupted database record — that causes a failure on Ordergroove’s end. They are retried indefinitely until successful. In most cases, Ordergroove would need to resolve the issue for the order to place successfully. If you are seeing the same order being placed multiple times, please open a ticket with our Support Team.

Q: What does “pending placement” mean?

A “pending placement” status refers to an order that has been moved to the queue and is waiting to be sent by Ordergroove to your order placement endpoint.

Q: Why is this old order still in “pending placement”?

Each time an order is attempted, it receives this status before it is sent to your endpoint, usually indicating that there are other orders processing ahead of it in the queue. An order may leave this status and later re-enter it during a retry. If this status persists, you may be experiencing other order placement errors which are addressed in subsequent questions; see other articles in this section.

Q: Why aren't orders placing?

Have you noticed subscription orders haven’t generated in your e-commerce platform for the day? There are a few items you could validate to ensure they are working correctly.

Orders Report:
Check the Orders Report to validate orders should have been placed today. Navigate to RC3 > Data Exports > Order CSV and download the file for today’s date and all statuses.
RC3 Configurations:
Navigate to RC3 > Settings > Order Placement and check:
- Credentials are added for a username and password protected endpoint (if applicable)
- The correct order placement URL is entered to receive orders
  - Using a Cartridge or App? The redirect for order placement should populate within RC3 > Settings > Order Placement > URL, just plug in your storefront URL in front of the redirect
- The order placement hour configured is not in the future
  - Note: Order placement hours are in Central Standard Time
- Cross Reference the products listed in your orders report to see if they are in stock within your Product Catalog
  - Ordergroove will not place orders for products for which we receive an OOS flag within the Product Feed.
  - The customer will be notified that their product is OOS
Order Placement Tool:
- Navigate to System Tools > Order Placement and see if Response logs are listed for the current date. If there are logs, open a few to see if they indicate any technical error that would potentially be impacting all customers. Technical issues on order placement may require further investigating and debugging on the client-side, as Ordergroove does not have visibility into downstream systems once the order has been placed.
Salesforce Commerce Cloud Merchants:
While there is an option to password protect your staging storefront during the integration, you must remove the protection for order placement testing. Additionally, please ensure that you do not have your storefront credentials entered within RC3 under RC3 > Settings > Order Placement.
BigCommerce Merchants:
Ordergroove will need to provide a Webhook for your order placement endpoint to be added in RC3 > Settings > Order Placement > URL. The Webhook will be provided when your callback URLs are provided.

Out of Stock (OOS) FAQ

For common questions about Ordergroove's Out of Stock process, take a look at the dedicated FAQ article.