Listings APIListings API
Se connecter
POST/api/v4/posts

Créer une publication d’offre

Crée une publication sociale OFFER avec un coupon, une remise et des conditions, publiée sur les sites choisis pour un ou plusieurs établissements.

Nécessite une clé API. Consultez Authentification pour le format de l’en-tête et la rotation des clés.

Paramètres

Corps

NomTypeObligatoireDescription
inputobjectobligatoireWrapper object. Every field below is a property of `input`, the entire body must be nested under it.
input.postNamestringobligatoireInternal name for the campaign (not shown to customers).
input.locationIdsarray of stringsobligatoireBase64-encoded location IDs to publish to (e.g. `TG9jYXRpb246MTgwMDI4OQ==`).
input.postTypestringobligatoireMust be `OFFER`. One of EVENT, OFFER, ANNOUNCEMENT, COVID19, PRODUCT.
input.postSitesarray of stringsobligatoireSites to publish to: `GOOGLE`, `FACEBOOK`.
input.postContextInfoobjectfacultatifOffer details: `{ title, couponCode, discount, redeemUrl, termsConditions, startDay, endDay }`. `title` labels the offer; `startDay`/`endDay` bound its validity.
input.postMessagearray of objectsfacultatifPer-site body text: `{ site, message }`. One entry per site in `postSites`.
input.postScheduledDatesobjectfacultatifWhen to publish/expire the post itself: `{ startDatetime, endDatetime, removalSites }`. Distinct from the offer validity in `postContextInfo`.
input.postCtaarray of objectsfacultatifOptional 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.postMediaUrlarray of objectsfacultatifOptional media per site: `{ site, url, type }` where `type` is IMAGE or VIDEO.
input.clientMutationIdstringfacultatifOptional client token returned unchanged in the response for correlation.

Exemple de requête

Corps prêt à coller. Remplacez les identifiants et valeurs d’exemple par les vôtres.

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

Réponses

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.

Crée une publication d’offre : une carte promotionnelle avec un code de réduction, une remise, un lien pour bénéficier de l’offre et des conditions. Les détails de l’offre se trouvent dans postContextInfo (title, couponCode, discount, redeemUrl, termsConditions, startDay, endDay). Les offres s’associent naturellement à un appel à l’action GET_OFFER.

Cas d’utilisation : lancer une promotion à durée limitée. Lancez une offre « Diwali : 25 % de réduction » pour Jenny Home, valable du 22 juin au 6 juillet, avec le coupon DIWALI25 et une URL pour bénéficier de l’offre. Définissez postType: "OFFER", renseignez postContextInfo et ajoutez un appel à l’action GET_OFFER. L’appel renvoie status: INPROGRESS ; vérifiez que la publication apparaît sur chaque site avec GET /posts/{postId}, et supprimez-la avant l’échéance avec DELETE /posts/{postId} si la promotion prend fin.

Remarques.

  • Le corps de la requête doit être encapsulé dans un objet input : chaque champ est une propriété de input. Un corps à plat, non encapsulé, est rejeté avec un statut HTTP 400 (Variable "$input" of required type "CreateSocialPostMutationInput!" was not provided).
  • postContextInfo.startDay/endDay délimitent la période de validité de l’offre ; utilisez postScheduledDates si vous souhaitez également planifier indépendamment les dates de publication et d’expiration de la publication.
  • Fournissez une entrée postMessage pour chaque site dans postSites.
  • Pour de simples actualités, utilisez les annonces ; pour des manifestations à des dates précises, utilisez les événements.

Opération d’écriture : non exécutée sur le compte réel. La requête et la réponse présentées sont construites à partir du schéma de l’API ; cette opération publie sur de vrais profils Google/Facebook lorsqu’elle est exécutée.

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