POST/api/v4/posts

建立優惠貼文

建立包含優惠券、折扣與條款的 OFFER 社群貼文，並發布至 1 個或多個地點所選的網站。

需要 API 金鑰。標頭格式與金鑰輪替請參閱驗證。

參數

請求主體

名稱	類型	必填	說明
input	object	必填	Wrapper object. Every field below is a property of `input`, the entire body must be nested under it.
input.postName	string	必填	Internal name for the campaign (not shown to customers).
input.locationIds	array of strings	必填	Base64-encoded location IDs to publish to (e.g. `TG9jYXRpb246MTgwMDI4OQ==`).
input.postType	string	必填	Must be `OFFER`. One of EVENT, OFFER, ANNOUNCEMENT, COVID19, PRODUCT.
input.postSites	array of strings	必填	Sites to publish to: `GOOGLE`, `FACEBOOK`.
input.postContextInfo	object	選填	Offer details: `{ title, couponCode, discount, redeemUrl, termsConditions, startDay, endDay }`. `title` labels the offer; `startDay`/`endDay` bound its validity.
input.postMessage	array of objects	選填	Per-site body text: `{ site, message }`. One entry per site in `postSites`.
input.postScheduledDates	object	選填	When to publish/expire the post itself: `{ startDatetime, endDatetime, removalSites }`. Distinct from the offer validity in `postContextInfo`.
input.postCta	array of objects	選填	Optional call-to-action per site: `{ site, type, url }`. The `CTAType` enum accepts BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP, and GET_OFFER. There is no `REDEEM`. For offer posts, Google takes ORDER and Facebook takes GET_OFFER.
input.postMediaUrl	array of objects	選填	Optional media per site: `{ site, url, type }` where `type` is IMAGE or VIDEO.
input.clientMutationId	string	選填	Optional client token returned unchanged in the response for correlation.

請求範例

可直接貼上的請求主體。請將預留位置 ID 與值換成您自己的。

Request body

{  "input": {    "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" }    ]  }}

回應

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

Response

{  "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]      }    }  }}

400Bad request, the body was not wrapped in `input` (error message: `Variable "$input" of required type "CreateSocialPostMutationInput!" was not provided`).

401Unauthenticated, missing or invalid API key.

建立優惠貼文：包含優惠碼、折扣、兌換連結與條款的促銷卡片。優惠詳情位於 postContextInfo（title、couponCode、discount、redeemUrl、termsConditions、startDay、endDay）。優惠適合搭配 GET_OFFER CTA。

使用案例：舉辦限時促銷活動。為 Jenny Home 推出「排燈節 25% 折扣」優惠，有效期間為 6 月 22 日至 7 月 6 日，並提供優惠碼 DIWALI25 與兌換 URL。設定 postType: "OFFER"、填寫 postContextInfo，並加入 GET_OFFER CTA。此呼叫會傳回 status: INPROGRESS；使用 GET /posts/{postId} 確認貼文已發布至每個網站，若促銷活動結束，則使用 DELETE /posts/{postId} 提前刪除貼文。

注意事項。

請求主體必須包在 input 物件中：每個欄位都是 input 的屬性。未包裝的扁平主體會遭到拒絕，並傳回 HTTP 400（Variable "$input" of required type "CreateSocialPostMutationInput!" was not provided）。
postContextInfo.startDay／endDay 界定優惠的有效期間；若您也想獨立排定貼文的發布／到期時間，請使用 postScheduledDates。
請為 postSites 中的每個網站提供一筆 postMessage 項目。
一般更新請使用公告；有指定日期的活動請使用活動。

寫入操作：未對正式帳戶執行。此處顯示的請求與回應是依據 API 結構描述建立的；執行時，這項操作會將貼文發布至真實的 Google／Facebook 商家檔案。

Request

curl -X POST 'https://listingsapi.com/api/v4/posts' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "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"        }      ]    }  }'

Run in playground