App Store Connect API for customer reviews

1. 1In App Store Connect, open Users and Access, then the Integrations tab, and select App Store Connect API.
2. 2With Team Keys selected, click Generate API Key, name it and choose its role.
3. 3Download the private key and note the key ID and the issuer ID. The private key downloads only once, and Apple doesn't keep a copy.

Only an Admin can create team keys, and a team key reaches all your apps whatever its role. So pick the narrowest role that does the job: in App Store Connect, Customer Support is the role made for answering reviews.

• Sign a JSON Web Token with ES256 and your private key. Header: alg ES256, kid your key ID, typ JWT.
• Payload: iss your issuer ID, iat now, exp at most 20 minutes later, and aud set to appstoreconnect-v1.
• Send it as Authorization: Bearer <token> and reuse it until it expires.

GET /v1/apps/{id}/customerReviews lists the reviews of one app; the id comes from GET /v1/apps. Useful parameters:

• sort=-createdDate puts the newest first. createdDate, rating and -rating work too, one at a time.
• filter[rating]=1,2 keeps only those ratings, and filter[territory]=USA,GBR only those countries.
• exists[publishedResponse]=false returns reviews without a published reply.
• include=response adds your reply to each review. limit goes up to 200, and links.next points to the next page.

POST /v1/customerReviewResponses publishes a reply: a customerReviewResponses resource with your text in responseBody and the review in its review relationship.

{
  "data": {
    "type": "customerReviewResponses",
    "attributes": {
      "responseBody": "Thanks for the report. Version 2.4.1 fixes the crash on start."
    },
    "relationships": {
      "review": {
        "data": { "type": "customerReviews", "id": "<review id>" }
      }
    }
  }
}

• If the review already has a reply, the same request overwrites it.
• DELETE /v1/customerReviewResponses/{id} removes your reply.

• Replies don't appear on the App Store straight away; Apple says to allow up to 24 hours.
• Until then the reply's state is PENDING_PUBLISH; once it's live, PUBLISHED.
• The reviewer is notified and can update their review.

• Every response carries an X-Rate-Limit header such as user-hour-lim:3500;user-hour-rem:500;. The limit counts requests made with the same key over the past hour, and Apple says actual limits vary.
• Past the limit, requests fail with HTTP 429 and RATE_LIMIT_EXCEEDED: wait, then retry.
• A 403 means the key isn't allowed to make that request. A 409 on a reply means the data you sent isn't valid.

Merci AI does all of this for you. It reads your reviews with a key that only needs the Customer Support role, drafts a reply to each one in the language it was written in, and publishes through this same API only when you click Publish.