POST/api/v4/posts

Create an offer post

Creates an OFFER social post with a coupon, discount, and terms, published to the chosen sites for one or more locations.

Requires an API key. See Authentication for header format and key rotation.

Parameters

Body

Name	Type	Required	Description
postName	string	required	Internal name for the campaign (not shown to customers).
locationIds	array of strings	required	Base64-encoded location IDs to publish to (e.g. `TG9jYXRpb246MTgwMDI4OQ==`).
postType	string	required	Must be `OFFER`. One of EVENT, OFFER, ANNOUNCEMENT, COVID19, PRODUCT.
postSites	array of strings	required	Sites to publish to: `GOOGLE`, `FACEBOOK`.
postContextInfo	object	optional	Offer details: `{ title, couponCode, discount, redeemUrl, termsConditions, startDay, endDay }`. `title` labels the offer; `startDay`/`endDay` bound its validity.
postMessage	array of objects	optional	Per-site body text: `{ site, message }`. One entry per site in `postSites`.
postScheduledDates	object	optional	When to publish/expire the post itself: `{ startDatetime, endDatetime, removalSites }`. Distinct from the offer validity in `postContextInfo`.
postCta	array of objects	optional	Optional call-to-action per site: `{ site, type, url }`. Offers typically use `GET_OFFER` or `REDEEM`; allowed types: BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP, GET_OFFER.
postMediaUrl	array of objects	optional	Optional media per site: `{ site, url, type }` where `type` is IMAGE or VIDEO.
clientMutationId	string	optional	Optional client token echoed back in the response for correlation.

Sample request

Ready-to-paste body. Replace placeholder IDs and values with yours.

{
  "postName": "Diwali 25% Off",
  "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="],
  "postType": "OFFER",
  "postSites": ["GOOGLE"],
  "postContextInfo": {
    "title": "25% off storewide",
    "couponCode": "DIWALI25",
    "discount": "25%",
    "redeemUrl": "https://jennyhome.example/diwali",
    "termsConditions": "Valid in-store only through July 6. Cannot be combined with other offers.",
    "startDay": "2026-06-22",
    "endDay": "2026-07-06"
  },
  "postMessage": [
    { "site": "GOOGLE", "message": "Celebrate with us — 25% off everything in store this festive week." }
  ],
  "postCta": [
    { "site": "GOOGLE", "type": "GET_OFFER", "url": "https://jennyhome.example/diwali" }
  ],
  "postMediaUrl": [
    { "site": "GOOGLE", "url": "https://cdn.example.com/diwali.jpg", "type": "IMAGE" }
  ]
}

Responses

200Post accepted. Publishing runs asynchronously — the returned post starts as INPROGRESS.

{
  "data": {
    "createSocialPost": {
      "clientMutationId": null,
      "success": true,
      "errors": [],
      "socialPost": {
        "id": "U29jaWFsUG9zdDo0NDEyNA==",
        "name": "Diwali 25% Off",
        "status": "INPROGRESS",
        "type": "OFFER",
        "createdAt": "2026-06-20",
        "scheduledStartDate": "2026-06-22",
        "scheduledEndDate": "2026-07-06",
        "sites": ["GOOGLE"],
        "message": [
          { "site": "GOOGLE", "message": "Celebrate with us — 25% off everything in store this festive week." }
        ],
        "cta": [
          { "type": { "value": "GET_OFFER", "label": "Get offer" }, "url": "https://jennyhome.example/diwali", "site": "GOOGLE", "tinyUrl": null }
        ],
        "contextInfo": {
          "title": "25% off storewide",
          "couponCode": "DIWALI25",
          "discount": "25%",
          "redeemUrl": "https://jennyhome.example/diwali",
          "termsConditions": "Valid in-store only through July 6. Cannot be combined with other offers.",
          "startDay": "2026-06-22",
          "endDay": "2026-07-06",
          "startTime": null,
          "endTime": null,
          "locationType": null
        },
        "mediaUrl": [
          { "url": "https://cdn.example.com/diwali.jpg", "site": "GOOGLE", "type": "IMAGE" }
        ],
        "publishDetails": [
          { "site": "GOOGLE", "status": "PUBLISHING", "createdDate": "2026-06-20", "submissionError": null }
        ],
        "postLinks": [],
        "locationIds": [1800289]
      }
    }
  }
}

401Unauthenticated — missing or invalid API key.

Creates an offer post — a promotion card with a coupon code, discount, redeem link, and terms. The offer specifics live in postContextInfo (title, couponCode, discount, redeemUrl, termsConditions, startDay, endDay). Offers pair naturally with a GET_OFFER CTA.

Use case — run a time-boxed promotion. Launch a "Diwali 25% Off" offer for Jenny Home valid June 22–July 6, with coupon DIWALI25 and a redeem URL. Set postType: "OFFER", fill postContextInfo, and add a GET_OFFER CTA. The call returns status: INPROGRESS; verify it lands on each site with GET /posts/{postId}, and delete it early with DELETE /posts/{postId} if the promotion ends.

Notes.

The body is sent flat (top-level fields, no input wrapper).
postContextInfo.startDay/endDay bound the offer's validity; use postScheduledDates if you also want to schedule when the post publishes/expires independently.
Provide a postMessage entry for each site in postSites.
For plain updates use announcements; for dated happenings use events.

Write operation — not executed against the live account. The request and response shown are built from the API schema; this posts to real Google/Facebook profiles when run.

curl -X POST 'https://listingsapi.com/api/v4/posts' \
  -H "Authorization: API $LISTINGSAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "postName": "<postName>",
    "locationIds": "<locationIds>",
    "postType": "<postType>",
    "postSites": "<postSites>",
    "postContextInfo": "<postContextInfo>",
    "postMessage": "<postMessage>",
    "postScheduledDates": "<postScheduledDates>",
    "postCta": "<postCta>",
    "postMediaUrl": "<postMediaUrl>",
    "clientMutationId": "<clientMutationId>"
  }'

Run in playground