Plan a week of posts as drafts
- Credentials
- OAuth access token
- Scopes
ai:spend- Subscription
- Needs an active plan. Otherwise
403 subscription_locked. - Daily limit
- AI generations, 300 a day per store. Over the limit is
429 rate_limited. - Idempotency
- Send an
Idempotency-Keyheader. A retry with the same key does the work once.
5 to 7 drafts (fewer when the shop has fewer listings with photos: a listing is never used twice) from the shop's real listings (only ones with photos; at most the first 30 are offered), spread over the next seven days at sensible South African times, each with a Facebook and an Instagram caption in the shop's voice. They are DRAFTS with a suggested time and a reason ("Plan my week: ..."): nothing goes out until publishSocialPost or scheduleSocialPost. Instagram is only a channel when the Page has an Instagram account.
This differs from startStudioMake with kind: week, which writes the words but creates no drafts. One credit for the whole week, charged when the plan is written (403 insufficient_credits, over_credit_limit, ai_not_configured). Needs a connected Facebook Page (409 facebook_not_connected) and listings with photos (422 validation_error, "Add products with photos first").
The Idempotency-Key keeps a retry from planning, and charging for, a second week, even after a crash (the charge is written down when it is taken); a new key plans another week. A plan that comes back empty or fails charges nothing (502 generation_failed).
Access: OAuth scope ai:spend; write-gated by the subscription.
merchantOAuth ai:spendAuthorizationBearer <token>OAuth 2.1 (authorization code + PKCE S256, public clients, dynamic registration) for connected AI apps. Effective power is scopes granted AND the person's role today AND the plan. orders:refund, billing:write and team:write are opt-in on the consent screen. Write implies read for marketing:read and messages:read, so a grant holding marketing:write passes a marketing:read check, and messages:send passes messages:read.
Scope: ai:spend
storeId*stringA store the person can reach. Any other id answers 404, never 403.
Idempotency-Key*stringRequired on every write. Minted on the device when the person taps, reused on every retry. A write without one, or with one that does not match the pattern, is refused with 422 validation_error. Scoped to the token's subject, remembered 24 hours. A replay returns the first 2xx response with Idempotent-Replay: true; a request still running answers 409 in_flight; the same key with a different method, path or body answers 409 idempotency_key_reused; non-2xx results are not remembered. If the key store cannot be read nothing is processed and the answer is 503 idempotency_unavailable: retry with the same key.
^[A-Za-z0-9_-]{8,128}$Created
application/json- response
data*curl -X POST 'https://api.shopeazy.co/v1/merchant/stores/<storeId>/social/plan-week' \ -H 'Authorization: Bearer <access_token>' \ -H 'Idempotency-Key: <unique_key>'{ "data": { "created": 0, "postIds": [ "string" ] }}Save which events draft a social post by themselves PUT
Replaces all four switches; send all four. Saving the same values again changes nothing. Needs a connected Facebook Page. Access: OAuth scope `marketing:write`; write-gated by the subscription.
Make a social draft from a Library photo or video POST
Saves a draft post (`source: manual`) with the picture or video and the caption, for Facebook and Instagram; a video goes out as a Reel and a Facebook video. Nothing is posted: approve it with `publishSocialPost` or `scheduleSocialPost`. A sound is 422 `validation_error` ("Promote takes photos and videos, not sounds."). Linked to the listing the asset was made for, when it has one. Unlike the other social writes it does not need a connected Page to be saved. The `Idempotency-Key` keeps a retry from saving two drafts. Access: OAuth scope `marketing:write`; write-gated by the subscription.