PowerReviews Write API

[CommunityJedi22]

Welcome

The Write Services B2B Write-a-Review endpoints are intended to provide external integration endpoints to PowerReviews Write-a-Review for server-to-server implementations by external customers. These endpoints include:

• GetReviewTemplate - Retrieve the set of review questions (also known in PowerReviews terminology as a “review template”) for a specific page id, locale and client, and (optionally) a user ID. This response is fully augmented by local specific content where applicable.
• SubmitReview - Submits a user’s review data for a product.

Before you get started

The API key used with the Write API is different than the API key used for the reviews or display API. Before beginning, please make sure the API key being used is for the Write API.

First Steps

You will need to first retrieve the review template using the GetReviewTemplate endpoint. This must be done to retrieve the necessary values and identifiers.

Example: http://writeservices.powerreviews.com/api/b2b/writereview/review_template?apikey=<write_api_key>&merchant_id=<merchant_id>&page_id=<page_id>

The template identifiers vary based on the account and product. Different products can have different review forms if they have been configured in the PowerReviews backend. Only after you have the identifiers from the template can you use the SubmitReview call.

GetReviewTemplate will also give you information about each form field including but not limited to the field_type, required, input_type, answer_type, max_length

Submitting the Review

Once you have collected the review from the end-user, you will need to construct a POST API call using the “Submit a review” endpoint.

The header should be set as Content-Type: application/json

Construct the URL using the parameters specific to your account and the page_id for the particular product the review is for. Example: http://writeservices.powerreviews.com/api/b2b/writereview/submit_review?apikey=<write_api_key>&page_id=<page_id>&merchant_id=<merchant_id>&locale=en_US

The body of the POST, should include the full review as well as other fields. You will need to use the template identifiers that you retrieved from the Get Review Template endpoint as part of the body of this call. The structure of the body should match that of the example in the documentation.

Field Types

Simple

• answer_type: “text” - A field_type of simple with answer_type of text will correspond to a field where the user can write a string of text (e.g. Review Headline, Comments, Nickname, Location). Keep in mind that some of these fields have a max character limit.
• answer_type: “numeric” - A field_type of simple with answer_type of numeric will correspond to either the overall star rating field or a subrating field. This field expects an integer value in the set [1 - 5].

Collection

• answer_type: “single” - A field_type of collection with answer_type of single will correspond to a radio button or dropdown type field. That is, the user must select from a list of predefined options. Even though only a maximum of one answer option is permitted, this field must still be structured using an array. For example,
• "values":"[{"id": "78175", "value": "Yes, I would recommend this to a friend"}]"
• answer_type: “multiple” - A field_type of collection with answer_type of multiple will correspond to a checkbox type field. That is, the user may select multiple options. Answer options may be selected from a predefined list and/or answer options may be defined by the user. All answer options must be structured using an array. For example,
• "values":"[{"value":"Attractive Design", "id":"85099"}, {"value":"Durable", "id":"25997"}]"
• composite - This field type corresponds to an image or video upload.

Additional Fields Outside of the Review Form

• iovation_black_box - This field is required for authenticity/fraud detection purposes as well as review syndication. More information on how to get the iovation_black_box value can be found here: https://developers.powerreviews.com/Content/Write%20API/iOvation.htm
• ip_address - This field should be populated with the user’s IP address. This field is required as part of authenticity/fraud as well as review syndication.
• order_id - If the review is being solicited from a Post Purchase Follow Up Email, the order_id from the customer’s order may be submitted with the review for reporting purposes.
• source - This field should be set to web if the review is coming from a reviewer who is organically searching the site. This field should be set to email if the reviewer was directed to the form from a Post Purchase Follow Up Email. Setting this field to email will badge the review with the Verified Buyer badge.
• disclosure_code - This field may be set to sampling if the review was solicited as part of a sampling campaign. This field may be set to sweepstakes if the review was solicited as part of a sweepstakes campaign. If this field is used for either sampling or sweepstakes, then a disclosure text will be included as part of the review claiming that the review was written as part of sampling or sweepstakes.

Response

If a request fails to pass validation, a response similar to the GetReviewTemplate quest will be returned; however, only fields that failed validation will be returned and will have an error_message attribute will be populated.

Status codes

• 200 OK - Successful request
• 400 CouldNotReadRequest - Invalid JSON body or otherwise unreadable request body
• 400 Missing Merchant - Missing parameter combination to identify merchant account.
• 400 MissingParameter - General error message if a required parameter is missing. Message will identify the missing parameter.
• 400 Invalid Parameter - General error message if a parameter fails validation. Message will identify the missing parameter.
• 400 CouldNotSaveImage
• 400 ImageUploadNotEnabled
• 400 UnrecognizedField - Field provided has a key that is not part of the expected review template
• 400 ValidationFailure - One of the fields submitted failed validations
• 400 ReviewAlreadySubmitted - Returned if a review is identified as having already been submitted
• 401 MerchantNotEnabled
• 401 MerchantNotEnabledForSSL
• 401 Missing API
• 403 Invalid API Key
• 405 Method Not Allowed - Returned if your request is not HTTPS
• 413 ReviewTooLong - Returned if the review content was too large for the internal system to handle
• 415 Unsupported Media Type - Returned if the body of your POST request is not JSON
• 504 InternalError - Returned if an unexpected error was encountered in the server

400 Error Details When a field has failed validation, a 400 status_code is returned with the message "Please update the highlighted fields below to continue with your submission." When that occurs, a JSON response is provided with a separate error_code object within each individual field object.

Example:

{
"id": "ag1_o44240",
"field_type": "simple",
"key": "headline",
"label": "Review Title",
"required": true,
"helper_text": "Include a short, descriptive title to publish with your review",
"error_message": {
"error_code": "RequiredField",
"message": "Required Field"
},
"input_type": "TextBox",
"answer_type": "text",
"max_length": 60
}

Possible error codes for individual fields are:

• RequiredField - RequiredField
• RestrictedWord - One or more words were flagged by our profanity/restricted word filter.

TTL

The time-to-live value for the PowerReviews Write API is 6 hours.

[Ramya]

Hi Team,

We are from Fivetran, a data integration platform that syncs data from source systems into customer destinations such as Snowflake, BigQuery, Redshift, etc.

We are currently investigating an issue reported by a mutual customer where API syncs are failing due to the following error returned by the PowerReviews API:

Invalid Merchant ID [923023]

During the sync, the API returns merchant ID 923023, which is then used in subsequent requests. However, those requests fail with a 400 response indicating that the merchant ID is invalid.

We would like to understand the expected behavior for this scenario and would appreciate your guidance on the following:

• Can a merchant ID that was previously returned by the API later become invalid?
• Is merchant ID 923023 currently active, deleted, deactivated, or otherwise inaccessible?
• Are there any known scenarios where APIs may continue returning references to merchants that are no longer valid?
• Should consumers of the API expect and handle these merchant IDs differently?
• Is there an endpoint or validation mechanism available to verify whether a merchant ID is still valid before making dependent requests?

At the moment, the issue is impacting incremental data synchronization for the customer, and we are trying to determine whether this is expected source behavior or if there is an underlying configuration issue associated with this merchant.

Any additional details, recommendations, or documentation you can provide would be greatly appreciated.

Thank you for your assistance.

[travis_smith]

Hi @Ramya , and welcome! We’re glad to have you here, especially as one of the first members of the community. Thanks for taking the time to share such a detailed overview of what you’re seeing.

Based on the nature of your questions, particularly around merchant ID validity and account-specific behavior, this is something we’ll want to review more closely on a case-by-case basis.

Some of the details you’re asking about (such as whether a specific merchant ID is active, deactivated, or otherwise inaccessible) can involve account-level configuration and data that we’re not able to fully investigate within the community forum.

To make sure you get the most accurate and complete guidance, we recommend opening a support ticket so our team can take a deeper look into the specific merchant and API activity involved. You can reach us here:

1WorldSync Global Community - 1WorldSync Customer Community

When you submit the ticket, it would be helpful to include:

• The impacted merchant ID(s) (such as 923023)
• Example API requests/responses showing the behavior
• Any relevant timestamps or sync job details from your Fivetran process

In parallel, you may also find additional context in our Write API documentation here: https://apidocs.powerreviews.com/docs/powerreviews-write-api/0865091e52b74-power-reviews-write-api

Once a ticket is opened, our team will be able to investigate whether this is expected behavior, a configuration issue, or something else affecting the sync.

Thanks again for reaching out.