{"method":"POST","path":"https://api.revcent.com/v2/sales/pending/{sale_id}","summary":"Update A Pending Sale","description":"Update an existing pending sale using the sale ID of a previously created pending sale. This will not process payment.

You can add/modify all attributes such as payment details, addresses, products and more.

Important: If adding/modifying any products, shipping, tax or discounts, please refer to the pending_options object for specific update settings. View markdown documentation at https://revcent.com/documentation/markdown/mcp/operation/UpdatePendingSale.md for an in-depth overview of this operation.","operationId":"UpdatePendingSale","parameters":[{"in":"path","name":"sale_id","description":"The sale ID generated when the pending sale was first created.","required":true,"schema":{"type":"string","description":"A 20 character sale ID.","minLength":20,"maxLength":20}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"campaign":{"type":"string","title":"Campaign ID","description":"A 20 character campaign ID.","minLength":20,"maxLength":20},"iso_currency":{"description":"The three digit ISO 4217 currency code.","type":"string","minLength":3,"maxLength":3},"ip_address":{"description":"The customer IP address.","type":"string"},"credit_card":{"additionalProperties":false,"description":"If you wish to add credit card payment information to the pending sale, which will be used when processing the pending sale for payment.","properties":{"card_number":{"description":"The full credit card number.","type":"string"},"exp_month":{"description":"The credit card expiration month as a one or two digit integer, i.e. MM.","type":"integer"},"exp_year":{"description":"The credit card expiration year as a two digit integer, i.e. YY.","type":"integer"},"card_code":{"description":"The credit card code as a string. Depending on the card type this can be different lengths.","type":"string"},"three_ds":{"description":"Optional 3DS if payment_type is credit_card. If you are using 3DS you can send RevCent the 3DS response values, which RevCent will pass to the processor.","additionalProperties":false,"properties":{"enabled":{"description":"Indicating whether or not RevCent should parse 3DS variables to send to the processor. Must be set to true if using 3DS during checkout and sending 3DS values to the processor. Default is false.","type":"boolean"},"version":{"description":"The 3DS version. Example: '2.1.0' or '2.2.0'.","type":"string"},"eci":{"description":"The eCommerce indicator. Indicates the result of the attempt to authenticate the cardholder. On successful authentications.","type":"string"},"cavv":{"description":"Cardholder Authentication Verification Value. On all successful authentications.","type":"string"},"xid":{"description":"The transaction identifier from authentication processing. Occasionally provided for some card brands.","type":"string"},"directory_server_id":{"description":"A transaction identifier assigned by the directory server. On all successful authentications.","type":"string"},"authentication_response":{"description":"Describing if a customer was successfully verified or attempted. On successful authentications.","type":"string"},"acs_transaction_id":{"description":"Access Control Server (ACS) transaction identifier.","type":"string"},"algorithm":{"description":"3DS algorithm used.","type":"string"},"directory_response":{"description":"3DS directory server response.","type":"string"},"enrollment_response":{"description":"Verify enrollment response/status.","type":"string"},"three_ds_server_transaction_id":{"description":"3DS server transaction id.","type":"string"}},"type":"object"}},"type":"object","required":["card_number","exp_month","exp_year"]},"customer":{"description":"The customer object receives first priority as details when creating a new customer.","additionalProperties":false,"properties":{"first_name":{"type":"string","description":"The customer first name."},"last_name":{"type":"string","description":"The customer last name."},"address_line_1":{"type":"string","description":"The customer first address line."},"address_line_2":{"type":"string","description":"The customer second address line."},"city":{"type":"string","description":"The customer city."},"state":{"type":"string","description":"The customer state."},"zip":{"type":"string","description":"The customer ZIP and or postal code."},"country":{"type":"string","description":"The customer country in three letter ISO 3166-1 alpha-3 format."},"company":{"type":"string","description":"The customer company."},"email":{"type":"string","format":"email","description":"The customer email."},"phone":{"type":"string","description":"The customer phone."}},"type":"object","required":["first_name","last_name","email"]},"bill_to":{"description":"To use as the billing information. If not present the customer object will be used. Useful when simultaneously adding a credit card with separate billing information.","additionalProperties":false,"properties":{"first_name":{"type":"string","description":"The bill to first name."},"last_name":{"type":"string","description":"The bill to last name."},"address_line_1":{"type":"string","description":"The bill to first address line."},"address_line_2":{"type":"string","description":"The bill to second address line."},"city":{"type":"string","description":"The bill to city."},"state":{"type":"string","description":"The bill to state."},"zip":{"type":"string","description":"The bill to ZIP and or postal code."},"country":{"type":"string","description":"The bill to country in three letter ISO 3166-1 alpha-3 format."},"company":{"type":"string","description":"The bill to company."},"email":{"type":"string","format":"email","description":"The bill to email."},"phone":{"type":"string","description":"The bill to phone."}},"type":"object","required":["first_name","last_name","email"]},"ship_to":{"description":"To use as the ship to information. If not present the customer object, or bill_to object will be used if either present in respective order.","additionalProperties":false,"properties":{"first_name":{"type":"string","description":"The shipping first name."},"last_name":{"type":"string","description":"The shipping last name."},"address_line_1":{"type":"string","description":"The shipping first address line."},"address_line_2":{"type":"string","description":"The shipping second address line."},"city":{"type":"string","description":"The shipping city."},"state":{"type":"string","description":"The shipping state."},"zip":{"type":"string","description":"The shipping ZIP and or postal code."},"country":{"type":"string","description":"The shipping country in three letter ISO 3166-1 alpha-3 format."},"company":{"type":"string","description":"The shipping company."},"email":{"type":"string","format":"email","description":"The shipping email."},"phone":{"type":"string","description":"The shipping phone."}},"type":"object","required":["first_name","last_name","email"]},"product":{"description":"The products to include in the sale request.","items":{"description":"An individual product","additionalProperties":false,"properties":{"id":{"title":"Product ID","type":"string","description":"A 20 character product ID.","minLength":20,"maxLength":20},"quantity":{"description":"The quantity being purchased. Default is 1.","type":"integer"},"price":{"description":"The price you wish to charge, if different from the product default price in RevCent.","type":"number","format":"float"},"metadata":{"items":{"additionalProperties":false,"properties":{"name":{"type":"string","description":"A name paired to the value for the metadata object. Limited to 100 characters in length.","minLength":1,"maxLength":100},"value":{"type":"string","description":"A value paired to the name for the metadata object. Limited to 255 characters in length.","minLength":1,"maxLength":255}},"type":"object","required":["name","value"]},"type":"array","description":"You have the option to provide metadata for an individual product when creating a sale. This metadata will be passed to the eventual product sale for the product, which is extremely useful for business metrics.

For example, if an individual product within a sale is an upsell, you can include metadata with name: 'is_upsell' and value: 'true' for that product. This will allow you to easily run product level reports on all upsells by filtering for the metadata name of 'upsell' and value of 'true'."}},"type":"object","required":["id"]},"type":"array"},"shipping":{"description":"Shipping to include in the sale request. Please refer to our Provider Method Table at our knowledge base for the provider and method IDs.","items":{"description":"An individual shipping entry.","additionalProperties":false,"properties":{"amount":{"description":"The amount to charge for the specific shipping entry. A shipping amount can be 0.","type":"number","format":"float"},"provider":{"description":"The shipping provider. This will be included when creating a shipment at a fulfillment center. Please refer to our Provider Method Table at our knowledge base for the correct provider id.","type":"string"},"provider_method":{"description":"The shipping provider method. This will be included when creating a shipment at a fulfillment center. Please refer to our Provider Method Table at our knowledge base for the correct method id corresponding to the provider.","type":"string"},"name":{"description":"An optional name for the shipping entry.","type":"string"},"description":{"description":"An optional description for the shipping entry.","type":"string"},"metadata":{"items":{"additionalProperties":false,"properties":{"name":{"type":"string","description":"A name paired to the value for the metadata object. Limited to 100 characters in length.","minLength":1,"maxLength":100},"value":{"type":"string","description":"A value paired to the name for the metadata object. Limited to 255 characters in length.","minLength":1,"maxLength":255}},"type":"object","required":["name","value"]},"type":"array","description":"You have the option to provide metadata for an individual shipping entry when creating a sale. This metadata will be passed to the eventual shipping item for the sale."}},"type":"object","required":["amount"]},"type":"array"},"tax":{"description":"Tax to charge in the sale request. Can create multiple tax entries to itemize separate taxes.","items":{"description":"An individual tax entry.","additionalProperties":false,"properties":{"amount":{"description":"The amount to charge for the specific tax entry.","type":"number","format":"float"},"name":{"description":"An optional name for the tax entry.","type":"string"},"description":{"description":"An optional description for the tax entry.","type":"string"},"metadata":{"items":{"additionalProperties":false,"properties":{"name":{"type":"string","description":"A name paired to the value for the metadata object. Limited to 100 characters in length.","minLength":1,"maxLength":100},"value":{"type":"string","description":"A value paired to the name for the metadata object. Limited to 255 characters in length.","minLength":1,"maxLength":255}},"type":"object","required":["name","value"]},"type":"array","description":"You have the option to provide metadata for an individual tax entry when creating a sale. This metadata will be passed to the eventual tax item for the sale."}},"type":"object","required":["amount"]},"type":"array"},"discount":{"description":"Include one or more discount entries which will be used to automatically apply discounts to a sale. Can be a fixed amount or a percentage of the sales total.","items":{"description":"An individual discount entry.","additionalProperties":false,"properties":{"discount_value":{"description":"The coupon discount value relative to the discount_type.","type":"number","format":"float"},"discount_type":{"description":"The coupon discount type, either percent or amount. RevCent will calculate the discount if percent.","type":"string","enum":["percent","amount"]},"name":{"description":"An optional name for the discount entry.","type":"string"},"description":{"description":"An optional description for the discount entry.","type":"string"},"apply_to_product":{"description":"Whether to apply the discount to products purchased. Default is true. Set to false if discount should only apply to shipping.","type":"boolean"},"apply_to_shipping":{"description":"Whether to apply the discount to shipping. Default is true. Set to false if discount should only apply to products purchased.","type":"boolean"}},"type":"object","required":["discount_value","discount_type"]},"type":"array"},"internal_sale_id":{"description":"An optional internal sale ID, i.e. a third party order ID. For records purposes only.","type":"string"},"internal_customer_id":{"description":"An optional internal customer ID, i.e. a third party customer ID. For records purposes only.","type":"string"},"metadata":{"items":{"additionalProperties":false,"properties":{"name":{"type":"string","description":"A name paired to the value for the metadata object. Limited to 100 characters in length.","minLength":1,"maxLength":100},"value":{"type":"string","description":"A value paired to the name for the metadata object. Limited to 255 characters in length.","minLength":1,"maxLength":255}},"type":"object","required":["name","value"]},"type":"array","description":"You have the option to provide metadata for a sale, which will be passed down to all items created as a result of the sale, i.e. the customer, product sales, shipping, tax. This is extremely useful for adding information you wish to view or use for reporting.

Visitor Tracking: If the sale took place on a website, and you have tracking domain DNS set up in RevCent for the website, you must include the following metadata from the visitor/session cookie for the sale:
1. {'name': 'revcent_track_id', 'value': '[the value of visitor/session cookie.revcent_track_id]'}
2. {'name': 'revcent_entry_id', 'value': '[the value of visitor cookie.revcent_entry_id]'}

Offline Payments: For offline payment sales involving a third party payment processor you must include three metadata entries to ensure proper association of the sale within RevCent to the third party:
1. {'name': 'offline_payment_third_party', 'value': 'sezzle | afterpay | klarna | affirm | amazon_pay'}
2. {'name': 'offline_payment_third_party_transaction_id', 'value': '[the transaction ID from the third party]'}
3. {'name': 'offline_payment_third_party_integration_id', 'value': '[the RevCent ID of the third party integration within your account for the third party processor]'}"},"pending_options":{"description":"When updating a pending sale you have options available that allow you to specify what actions occur given specific conditions.","additionalProperties":false,"properties":{"exists_options":{"description":"The options for each request entity, in which to update the pending sale for existing entities.","additionalProperties":false,"properties":{"product":{"type":"string","description":"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.","enum":["replace","skip","merge_replace","merge_skip","merge_combine"],"x-extra-info":"Enum Definitions:
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":{"type":"string","description":"What to do if shipping already exists in the pending sale.","enum":["replace","skip"],"x-extra-info":"Enum Definitions:
replace
Will replace existing shipping with new shipping. Default

skip
Will skip if shipping exists.
"},"tax":{"type":"string","description":"What to do if tax already exists in the pending sale.","enum":["replace","skip"],"x-extra-info":"Enum Definitions:
replace
Will replace existing tax with new tax. Default

skip
Will skip if tax exists.
"},"discount":{"type":"string","description":"What to do if discounts already exist in the pending sale.","enum":["replace","skip"],"x-extra-info":"Enum Definitions:
replace
Will replace existing discounts with new discounts. Default

skip
Will skip if discounts exist.
"}},"type":"object"}},"type":"object"}},"type":"object","additionalProperties":false,"required":["campaign"]}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"description":"","properties":{"api_call_id":{"type":"string","description":"A 20 character API call ID.","minLength":20,"maxLength":20},"api_call_unix":{"description":"Unix timestamp of when the API call was initiated.","type":"integer","format":"unix-time"},"code":{"description":"API call response code.","type":"integer","format":"int32","enum":[1]},"campaign_id":{"type":"string","title":"Campaign ID","description":"A 20 character campaign ID.","minLength":20,"maxLength":20},"customer_id":{"title":"Customer ID","type":"string","description":"A 20 character customer ID.","minLength":20,"maxLength":20},"sale_id":{"type":"string","description":"A 20 character sale ID.","minLength":20,"maxLength":20},"result":{"type":"string"}},"type":"object","additionalProperties":false}}},"description":"Successful response."},"default":{"content":{"application/json":{"schema":{"description":"","properties":{"api_call_id":{"type":"string","description":"A 20 character API call ID.","minLength":20,"maxLength":20},"api_call_unix":{"description":"Unix timestamp of when the API call was initiated.","type":"integer","format":"unix-time"},"code":{"description":"This value indicates that there is an error. Will always be 0.","type":"integer","enum":[0]},"error_code":{"description":"The specific error code.","type":"string"},"message":{"description":"A human readable description of the error.","type":"string"},"result":{"description":"A description of the API call result.","type":"string"}},"title":"APIStandardErrors","type":"object","additionalProperties":false}}},"description":"Error response."}}}