@kirimdev/sdk 3.1.1 → 3.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. package/dist/client.d.ts +4 -1
  2. package/dist/client.d.ts.map +1 -1
  3. package/dist/client.js +8 -1
  4. package/dist/client.js.map +1 -1
  5. package/dist/errors.js +16 -0
  6. package/dist/errors.js.map +1 -1
  7. package/dist/generated/schema.d.ts +1164 -102
  8. package/dist/generated/version.d.ts +2 -0
  9. package/dist/generated/version.d.ts.map +1 -0
  10. package/dist/generated/version.js +6 -0
  11. package/dist/generated/version.js.map +1 -0
  12. package/dist/generated/version.ts +6 -0
  13. package/dist/index.d.ts +2 -0
  14. package/dist/index.d.ts.map +1 -1
  15. package/dist/index.js.map +1 -1
  16. package/dist/resources/customers.d.ts +148 -0
  17. package/dist/resources/customers.d.ts.map +1 -0
  18. package/dist/resources/customers.js +96 -0
  19. package/dist/resources/customers.js.map +1 -0
  20. package/dist/resources/templates.d.ts +18 -0
  21. package/dist/resources/templates.d.ts.map +1 -1
  22. package/dist/resources/templates.js +16 -0
  23. package/dist/resources/templates.js.map +1 -1
  24. package/openapi.json +1754 -76
  25. package/package.json +1 -1
package/openapi.json CHANGED
@@ -44,6 +44,10 @@
44
44
  "name": "Labels",
45
45
  "description": "Coloured tags for contacts and conversations. Team-scoped per Kirimdev's internal model."
46
46
  },
47
+ {
48
+ "name": "Customers",
49
+ "description": "End-customers (tenant-of-tenant) — your platform's own clients. Each Customer can connect their own WhatsApp accounts via setup links and you send messages on their behalf. Distinct from `Contacts`."
50
+ },
47
51
  {
48
52
  "name": "Webhook Subscriptions",
49
53
  "description": "Subscribe to events, rotate signing secrets, pause/resume delivery."
@@ -100,6 +104,50 @@
100
104
  "error"
101
105
  ]
102
106
  },
107
+ "WhatsappAccountEmbedded": {
108
+ "type": "object",
109
+ "properties": {
110
+ "phone_number": {
111
+ "type": [
112
+ "string",
113
+ "null"
114
+ ]
115
+ },
116
+ "phone_number_id": {
117
+ "type": [
118
+ "string",
119
+ "null"
120
+ ],
121
+ "example": "106540352242922",
122
+ "description": "Meta `business_phone_number_id` — use as the `{phone_number_id}` path segment in `/v1/{phone_number_id}/...` endpoints."
123
+ },
124
+ "customer": {
125
+ "type": [
126
+ "object",
127
+ "null"
128
+ ],
129
+ "properties": {
130
+ "id": {
131
+ "type": "string",
132
+ "example": "cus_01HXYZABCDEFGHJKMNPQRSTVWX"
133
+ },
134
+ "name": {
135
+ "type": "string"
136
+ }
137
+ },
138
+ "required": [
139
+ "id",
140
+ "name"
141
+ ],
142
+ "description": "End-customer (multi-tenant platform mode) that owns this account. NULL for direct-org accounts."
143
+ }
144
+ },
145
+ "required": [
146
+ "phone_number",
147
+ "phone_number_id",
148
+ "customer"
149
+ ]
150
+ },
103
151
  "Message": {
104
152
  "type": "object",
105
153
  "properties": {
@@ -145,7 +193,7 @@
145
193
  "properties": {
146
194
  "code": {
147
195
  "type": "string",
148
- "description": "Stable Kirim error code. Known values include `outside_24h_window`, `marketing_opted_out`, `marketing_blocked_by_user`, `recipient_unavailable`, `unsupported_message_type`, `account_restricted`, `account_locked`, `consent_required`, `permission_revoked`, `auth_expired`, `app_rate_limited`, `account_rate_limited`, `template_not_found`, `template_paused`, `template_policy_violation`, `flow_blocked`, `media_upload_failed`, `media_download_failed`, `undeliverable`, `policy_violation`, `upstream_error`."
196
+ "description": "Stable Kirim error code. Known values include `outside_24h_window`, `marketing_opted_out`, `marketing_blocked_by_user`, `recipient_unavailable`, `unsupported_message_type`, `account_restricted`, `account_locked`, `consent_required`, `customer_suspended`, `permission_revoked`, `auth_expired`, `app_rate_limited`, `account_rate_limited`, `template_not_found`, `template_paused`, `template_policy_violation`, `flow_blocked`, `media_upload_failed`, `media_download_failed`, `undeliverable`, `policy_violation`, `upstream_error`."
149
197
  },
150
198
  "message": {
151
199
  "type": "string"
@@ -208,18 +256,7 @@
208
256
  },
209
257
  "components": {},
210
258
  "whatsapp_account": {
211
- "type": "object",
212
- "properties": {
213
- "phone_number": {
214
- "type": [
215
- "string",
216
- "null"
217
- ]
218
- }
219
- },
220
- "required": [
221
- "phone_number"
222
- ]
259
+ "$ref": "#/components/schemas/WhatsappAccountEmbedded"
223
260
  },
224
261
  "provider_template_id": {
225
262
  "type": [
@@ -285,6 +322,14 @@
285
322
  "type": "string",
286
323
  "example": "connected",
287
324
  "description": "Lifecycle state of the account (e.g. `connected`, `disconnected`, `degraded`, `onboarding`)."
325
+ },
326
+ "customer_id": {
327
+ "type": [
328
+ "string",
329
+ "null"
330
+ ],
331
+ "example": "cus_01HXYZABCDEFGHJKMNPQRSTVWX",
332
+ "description": "Public id of the end-customer (multi-tenant platform mode) that owns this account. NULL for direct-org accounts. Filter the list endpoint via `?customer_id=cus_...`."
288
333
  }
289
334
  },
290
335
  "required": [
@@ -292,7 +337,8 @@
292
337
  "phone_number_id",
293
338
  "phone_number",
294
339
  "name",
295
- "status"
340
+ "status",
341
+ "customer_id"
296
342
  ]
297
343
  },
298
344
  "WebhookSubscription": {
@@ -539,18 +585,7 @@
539
585
  ]
540
586
  },
541
587
  "whatsapp_account": {
542
- "type": "object",
543
- "properties": {
544
- "phone_number": {
545
- "type": [
546
- "string",
547
- "null"
548
- ]
549
- }
550
- },
551
- "required": [
552
- "phone_number"
553
- ]
588
+ "$ref": "#/components/schemas/WhatsappAccountEmbedded"
554
589
  },
555
590
  "assignee": {
556
591
  "type": [
@@ -660,18 +695,7 @@
660
695
  "additionalProperties": {}
661
696
  },
662
697
  "whatsapp_account": {
663
- "type": "object",
664
- "properties": {
665
- "phone_number": {
666
- "type": [
667
- "string",
668
- "null"
669
- ]
670
- }
671
- },
672
- "required": [
673
- "phone_number"
674
- ]
698
+ "$ref": "#/components/schemas/WhatsappAccountEmbedded"
675
699
  },
676
700
  "created_at": {
677
701
  "type": "string",
@@ -750,6 +774,168 @@
750
774
  "updated_at"
751
775
  ]
752
776
  },
777
+ "Customer": {
778
+ "type": "object",
779
+ "properties": {
780
+ "id": {
781
+ "type": "string",
782
+ "example": "cus_01HXYZABCDEFGHJKMNPQRSTVWX"
783
+ },
784
+ "object": {
785
+ "type": "string",
786
+ "enum": [
787
+ "customer"
788
+ ]
789
+ },
790
+ "name": {
791
+ "type": "string"
792
+ },
793
+ "email": {
794
+ "type": [
795
+ "string",
796
+ "null"
797
+ ]
798
+ },
799
+ "status": {
800
+ "type": "string",
801
+ "enum": [
802
+ "pending",
803
+ "active",
804
+ "suspended",
805
+ "archived"
806
+ ]
807
+ },
808
+ "metadata": {
809
+ "type": [
810
+ "object",
811
+ "null"
812
+ ],
813
+ "additionalProperties": {}
814
+ },
815
+ "archived_at": {
816
+ "type": [
817
+ "string",
818
+ "null"
819
+ ],
820
+ "format": "date-time"
821
+ },
822
+ "team_id": {
823
+ "type": "string"
824
+ },
825
+ "created_at": {
826
+ "type": "string",
827
+ "format": "date-time"
828
+ },
829
+ "updated_at": {
830
+ "type": "string",
831
+ "format": "date-time"
832
+ }
833
+ },
834
+ "required": [
835
+ "id",
836
+ "object",
837
+ "name",
838
+ "email",
839
+ "status",
840
+ "metadata",
841
+ "archived_at",
842
+ "team_id",
843
+ "created_at",
844
+ "updated_at"
845
+ ]
846
+ },
847
+ "CustomerSetupLink": {
848
+ "type": "object",
849
+ "properties": {
850
+ "id": {
851
+ "type": "string",
852
+ "example": "csl_01HXYZABCDEFGHJKMNPQRSTVWX"
853
+ },
854
+ "object": {
855
+ "type": "string",
856
+ "enum": [
857
+ "customer_setup_link"
858
+ ]
859
+ },
860
+ "customer_id": {
861
+ "type": "string"
862
+ },
863
+ "status": {
864
+ "type": "string",
865
+ "enum": [
866
+ "active",
867
+ "consumed",
868
+ "expired",
869
+ "revoked"
870
+ ]
871
+ },
872
+ "token_last4": {
873
+ "type": "string"
874
+ },
875
+ "expires_at": {
876
+ "type": "string",
877
+ "format": "date-time"
878
+ },
879
+ "consumed_at": {
880
+ "type": [
881
+ "string",
882
+ "null"
883
+ ],
884
+ "format": "date-time"
885
+ },
886
+ "success_redirect_url": {
887
+ "type": [
888
+ "string",
889
+ "null"
890
+ ],
891
+ "format": "uri",
892
+ "description": "Where the tenant is redirected after successful Embedded Signup. We append `?customer_id=&account_id=&status=success` on the redirect."
893
+ },
894
+ "failure_redirect_url": {
895
+ "type": [
896
+ "string",
897
+ "null"
898
+ ],
899
+ "format": "uri",
900
+ "description": "Where the tenant is redirected on failure (link error, Meta signup cancelled, etc.). We append `?customer_id=&status=failed&reason=<code>`."
901
+ },
902
+ "created_at": {
903
+ "type": "string",
904
+ "format": "date-time"
905
+ }
906
+ },
907
+ "required": [
908
+ "id",
909
+ "object",
910
+ "customer_id",
911
+ "status",
912
+ "token_last4",
913
+ "expires_at",
914
+ "consumed_at",
915
+ "success_redirect_url",
916
+ "failure_redirect_url",
917
+ "created_at"
918
+ ]
919
+ },
920
+ "CustomerSetupLinkWithToken": {
921
+ "allOf": [
922
+ {
923
+ "$ref": "#/components/schemas/CustomerSetupLink"
924
+ },
925
+ {
926
+ "type": "object",
927
+ "properties": {
928
+ "setup_url": {
929
+ "type": "string",
930
+ "format": "uri"
931
+ }
932
+ },
933
+ "required": [
934
+ "setup_url"
935
+ ]
936
+ }
937
+ ]
938
+ },
753
939
  "MessageListItem": {
754
940
  "type": "object",
755
941
  "properties": {
@@ -813,7 +999,7 @@
813
999
  "properties": {
814
1000
  "code": {
815
1001
  "type": "string",
816
- "description": "Stable Kirim error code. Known values include `outside_24h_window`, `marketing_opted_out`, `marketing_blocked_by_user`, `recipient_unavailable`, `unsupported_message_type`, `account_restricted`, `account_locked`, `consent_required`, `permission_revoked`, `auth_expired`, `app_rate_limited`, `account_rate_limited`, `template_not_found`, `template_paused`, `template_policy_violation`, `flow_blocked`, `media_upload_failed`, `media_download_failed`, `undeliverable`, `policy_violation`, `upstream_error`."
1002
+ "description": "Stable Kirim error code. Known values include `outside_24h_window`, `marketing_opted_out`, `marketing_blocked_by_user`, `recipient_unavailable`, `unsupported_message_type`, `account_restricted`, `account_locked`, `consent_required`, `customer_suspended`, `permission_revoked`, `auth_expired`, `app_rate_limited`, `account_rate_limited`, `template_not_found`, `template_paused`, `template_policy_violation`, `flow_blocked`, `media_upload_failed`, `media_download_failed`, `undeliverable`, `policy_violation`, `upstream_error`."
817
1003
  },
818
1004
  "message": {
819
1005
  "type": "string"
@@ -1039,6 +1225,47 @@
1039
1225
  "request_id"
1040
1226
  ]
1041
1227
  },
1228
+ "SyncTemplatesResponse": {
1229
+ "type": "object",
1230
+ "properties": {
1231
+ "data": {
1232
+ "type": "object",
1233
+ "properties": {
1234
+ "object": {
1235
+ "type": "string",
1236
+ "enum": [
1237
+ "template_sync_result"
1238
+ ]
1239
+ },
1240
+ "synced": {
1241
+ "type": "integer",
1242
+ "example": 12
1243
+ },
1244
+ "created": {
1245
+ "type": "integer",
1246
+ "example": 2
1247
+ },
1248
+ "updated": {
1249
+ "type": "integer",
1250
+ "example": 10
1251
+ }
1252
+ },
1253
+ "required": [
1254
+ "object",
1255
+ "synced",
1256
+ "created",
1257
+ "updated"
1258
+ ]
1259
+ },
1260
+ "request_id": {
1261
+ "type": "string"
1262
+ }
1263
+ },
1264
+ "required": [
1265
+ "data",
1266
+ "request_id"
1267
+ ]
1268
+ },
1042
1269
  "CreateWebhookSubscriptionResponse": {
1043
1270
  "type": "object",
1044
1271
  "properties": {
@@ -1812,25 +2039,298 @@
1812
2039
  "data",
1813
2040
  "request_id"
1814
2041
  ]
1815
- }
1816
- },
1817
- "parameters": {}
1818
- },
1819
- "paths": {
1820
- "/health": {
1821
- "get": {
1822
- "tags": [
1823
- "Meta"
1824
- ],
1825
- "summary": "Liveness probe",
1826
- "description": "Unauthenticated health check. Returns 200 if the API is up.",
1827
- "responses": {
1828
- "200": {
1829
- "description": "API is healthy",
1830
- "content": {
1831
- "application/json": {
1832
- "schema": {
1833
- "type": "object",
2042
+ },
2043
+ "ListCustomersResponse": {
2044
+ "type": "object",
2045
+ "properties": {
2046
+ "data": {
2047
+ "type": "array",
2048
+ "items": {
2049
+ "$ref": "#/components/schemas/Customer"
2050
+ }
2051
+ },
2052
+ "has_more": {
2053
+ "type": "boolean"
2054
+ },
2055
+ "next_cursor": {
2056
+ "type": [
2057
+ "string",
2058
+ "null"
2059
+ ]
2060
+ },
2061
+ "request_id": {
2062
+ "type": "string"
2063
+ }
2064
+ },
2065
+ "required": [
2066
+ "data",
2067
+ "has_more",
2068
+ "next_cursor",
2069
+ "request_id"
2070
+ ]
2071
+ },
2072
+ "CreateCustomerResponse": {
2073
+ "type": "object",
2074
+ "properties": {
2075
+ "data": {
2076
+ "$ref": "#/components/schemas/Customer"
2077
+ },
2078
+ "request_id": {
2079
+ "type": "string"
2080
+ }
2081
+ },
2082
+ "required": [
2083
+ "data",
2084
+ "request_id"
2085
+ ]
2086
+ },
2087
+ "GetCustomerResponse": {
2088
+ "type": "object",
2089
+ "properties": {
2090
+ "data": {
2091
+ "allOf": [
2092
+ {
2093
+ "$ref": "#/components/schemas/Customer"
2094
+ },
2095
+ {
2096
+ "type": "object",
2097
+ "properties": {
2098
+ "whatsapp_accounts": {
2099
+ "type": "array",
2100
+ "items": {
2101
+ "type": "object",
2102
+ "properties": {
2103
+ "phone_number_id": {
2104
+ "type": [
2105
+ "string",
2106
+ "null"
2107
+ ]
2108
+ },
2109
+ "phone_number": {
2110
+ "type": [
2111
+ "string",
2112
+ "null"
2113
+ ]
2114
+ },
2115
+ "name": {
2116
+ "type": [
2117
+ "string",
2118
+ "null"
2119
+ ]
2120
+ },
2121
+ "status": {
2122
+ "type": "string"
2123
+ },
2124
+ "onboarded_at": {
2125
+ "type": [
2126
+ "string",
2127
+ "null"
2128
+ ],
2129
+ "format": "date-time"
2130
+ }
2131
+ },
2132
+ "required": [
2133
+ "phone_number_id",
2134
+ "phone_number",
2135
+ "name",
2136
+ "status",
2137
+ "onboarded_at"
2138
+ ]
2139
+ },
2140
+ "description": "WhatsApp accounts currently assigned to this customer."
2141
+ }
2142
+ },
2143
+ "required": [
2144
+ "whatsapp_accounts"
2145
+ ]
2146
+ }
2147
+ ]
2148
+ },
2149
+ "request_id": {
2150
+ "type": "string"
2151
+ }
2152
+ },
2153
+ "required": [
2154
+ "data",
2155
+ "request_id"
2156
+ ]
2157
+ },
2158
+ "UpdateCustomerResponse": {
2159
+ "type": "object",
2160
+ "properties": {
2161
+ "data": {
2162
+ "$ref": "#/components/schemas/Customer"
2163
+ },
2164
+ "request_id": {
2165
+ "type": "string"
2166
+ }
2167
+ },
2168
+ "required": [
2169
+ "data",
2170
+ "request_id"
2171
+ ]
2172
+ },
2173
+ "ArchiveCustomerResponse": {
2174
+ "type": "object",
2175
+ "properties": {
2176
+ "data": {
2177
+ "type": "object",
2178
+ "properties": {
2179
+ "id": {
2180
+ "type": "string"
2181
+ },
2182
+ "object": {
2183
+ "type": "string",
2184
+ "enum": [
2185
+ "customer"
2186
+ ]
2187
+ },
2188
+ "archived": {
2189
+ "type": "boolean",
2190
+ "enum": [
2191
+ true
2192
+ ]
2193
+ }
2194
+ },
2195
+ "required": [
2196
+ "id",
2197
+ "object",
2198
+ "archived"
2199
+ ]
2200
+ },
2201
+ "request_id": {
2202
+ "type": "string"
2203
+ }
2204
+ },
2205
+ "required": [
2206
+ "data",
2207
+ "request_id"
2208
+ ]
2209
+ },
2210
+ "ListCustomerSetupLinksResponse": {
2211
+ "type": "object",
2212
+ "properties": {
2213
+ "data": {
2214
+ "type": "array",
2215
+ "items": {
2216
+ "$ref": "#/components/schemas/CustomerSetupLink"
2217
+ }
2218
+ },
2219
+ "has_more": {
2220
+ "type": "boolean"
2221
+ },
2222
+ "next_cursor": {
2223
+ "type": [
2224
+ "string",
2225
+ "null"
2226
+ ]
2227
+ },
2228
+ "request_id": {
2229
+ "type": "string"
2230
+ }
2231
+ },
2232
+ "required": [
2233
+ "data",
2234
+ "has_more",
2235
+ "next_cursor",
2236
+ "request_id"
2237
+ ]
2238
+ },
2239
+ "CreateCustomerSetupLinkResponse": {
2240
+ "type": "object",
2241
+ "properties": {
2242
+ "data": {
2243
+ "$ref": "#/components/schemas/CustomerSetupLinkWithToken"
2244
+ },
2245
+ "request_id": {
2246
+ "type": "string"
2247
+ }
2248
+ },
2249
+ "required": [
2250
+ "data",
2251
+ "request_id"
2252
+ ]
2253
+ },
2254
+ "UpdateCustomerSetupLinkResponse": {
2255
+ "type": "object",
2256
+ "properties": {
2257
+ "data": {
2258
+ "$ref": "#/components/schemas/CustomerSetupLink"
2259
+ },
2260
+ "request_id": {
2261
+ "type": "string"
2262
+ }
2263
+ },
2264
+ "required": [
2265
+ "data",
2266
+ "request_id"
2267
+ ]
2268
+ },
2269
+ "RevokeCustomerSetupLinkResponse": {
2270
+ "type": "object",
2271
+ "properties": {
2272
+ "data": {
2273
+ "type": "object",
2274
+ "properties": {
2275
+ "id": {
2276
+ "type": "string"
2277
+ },
2278
+ "object": {
2279
+ "type": "string",
2280
+ "enum": [
2281
+ "customer_setup_link"
2282
+ ]
2283
+ },
2284
+ "revoked": {
2285
+ "type": "boolean",
2286
+ "enum": [
2287
+ true
2288
+ ]
2289
+ },
2290
+ "status": {
2291
+ "type": "string",
2292
+ "enum": [
2293
+ "active",
2294
+ "consumed",
2295
+ "expired",
2296
+ "revoked"
2297
+ ]
2298
+ }
2299
+ },
2300
+ "required": [
2301
+ "id",
2302
+ "object",
2303
+ "revoked",
2304
+ "status"
2305
+ ]
2306
+ },
2307
+ "request_id": {
2308
+ "type": "string"
2309
+ }
2310
+ },
2311
+ "required": [
2312
+ "data",
2313
+ "request_id"
2314
+ ]
2315
+ }
2316
+ },
2317
+ "parameters": {}
2318
+ },
2319
+ "paths": {
2320
+ "/health": {
2321
+ "get": {
2322
+ "tags": [
2323
+ "Meta"
2324
+ ],
2325
+ "summary": "Liveness probe",
2326
+ "description": "Unauthenticated health check. Returns 200 if the API is up.",
2327
+ "responses": {
2328
+ "200": {
2329
+ "description": "API is healthy",
2330
+ "content": {
2331
+ "application/json": {
2332
+ "schema": {
2333
+ "type": "object",
1834
2334
  "properties": {
1835
2335
  "data": {
1836
2336
  "type": "object",
@@ -1941,6 +2441,15 @@
1941
2441
  "required": false,
1942
2442
  "name": "status",
1943
2443
  "in": "query"
2444
+ },
2445
+ {
2446
+ "schema": {
2447
+ "type": "string",
2448
+ "pattern": "^cus_[0-9A-HJKMNP-TV-Z]{26}$"
2449
+ },
2450
+ "required": false,
2451
+ "name": "customer_id",
2452
+ "in": "query"
1944
2453
  }
1945
2454
  ],
1946
2455
  "responses": {
@@ -2003,7 +2512,7 @@
2003
2512
  "Messages"
2004
2513
  ],
2005
2514
  "summary": "Send a WhatsApp message or mark inbound as read",
2006
- "description": "Meta-style messages endpoint. Two operations share the same path, distinguished by the request body:\n\n**Outbound send** — body has a `type` field (`text`, `image`, `document`, `video`, `audio`, `template`, `interactive`). Body shape mirrors the Meta WhatsApp Cloud API; media variants accept either `link` (hosted URL) or `id` (Meta uploaded media). The sender is the WhatsApp account identified by `phone_number_id` in the URL path; there is no `from` field in the body. Pass `Idempotency-Key` to safely retry on network failure.\n\n**Read receipt** — body has `status: \"read\"` + `message_id` (the inbound wamid from your webhook). Sends a read receipt back to the sender so the double-tick turns blue on their phone. Optional `typing_indicator: { type: \"text\" }` shows a typing bubble alongside the receipt; Meta auto-dismisses after ~25 seconds or on first outbound message.\n\n**Pre-send validation** — the API performs compliance checks before queuing the send. A 422 response with `error.code` set to `marketing_opted_out` indicates the recipient has stopped marketing messages from your business (the customer did this via the WhatsApp app menu — webhook `user_preferences` notifies you of the change). `account_restricted` indicates Meta has restricted your WhatsApp account; check the account status via the dashboard. `consent_required` indicates the recipient has not opted in. `upstream_error` indicates the WhatsApp account is disconnected. None of these are retryable until the underlying condition changes.",
2515
+ "description": "Meta-style messages endpoint. Two operations share the same path, distinguished by the request body:\n\n**Outbound send** — body has a `type` field (`text`, `image`, `document`, `video`, `audio`, `template`, `interactive`). Body shape mirrors the Meta WhatsApp Cloud API; media variants accept either `link` (hosted URL) or `id` (Meta uploaded media). The sender is the WhatsApp account identified by `phone_number_id` in the URL path; there is no `from` field in the body. Pass `Idempotency-Key` to safely retry on network failure.\n\n**Read receipt** — body has `status: \"read\"` + `message_id` (the inbound wamid from your webhook). Sends a read receipt back to the sender so the double-tick turns blue on their phone. Optional `typing_indicator: { type: \"text\" }` shows a typing bubble alongside the receipt; Meta auto-dismisses after ~25 seconds or on first outbound message.\n\n**Pre-send validation** — the API performs compliance checks before queuing the send. A 422 response with `error.code` set to `marketing_opted_out` indicates the recipient has stopped marketing messages from your business (the customer did this via the WhatsApp app menu — webhook `user_preferences` notifies you of the change). `account_restricted` indicates Meta has restricted your WhatsApp account; check the account status via the dashboard. `consent_required` indicates the recipient has not opted in. `customer_suspended` indicates the operator has suspended (or archived) the customer that owns this WhatsApp account; sends are blocked until the customer is unsuspended via the dashboard. `upstream_error` indicates the WhatsApp account is disconnected. None of these are retryable until the underlying condition changes.",
2007
2516
  "security": [
2008
2517
  {
2009
2518
  "bearerAuth": []
@@ -3729,26 +4238,136 @@
3729
4238
  }
3730
4239
  }
3731
4240
  },
3732
- "/webhook_subscriptions": {
4241
+ "/{phone_number_id}/templates/sync": {
3733
4242
  "post": {
3734
4243
  "tags": [
3735
- "Webhook Subscriptions"
4244
+ "Templates"
3736
4245
  ],
3737
- "summary": "Create a webhook subscription",
3738
- "description": "Create a webhook subscription. The response carries `initial_secret` ONCE — store it server-side immediately; Kirimdev cannot show it again.",
4246
+ "summary": "Sync templates from Meta",
4247
+ "description": "Pull the latest template inventory from Meta and upsert into the Kirim DB for this WhatsApp account. Idempotent — call any time, returns a `{ created, updated, synced }` summary. Useful for platform integrations (multi-tenant Customers) so they don't need to wait for an operator to click \"Sync\" in the dashboard.",
3739
4248
  "security": [
3740
4249
  {
3741
4250
  "bearerAuth": []
3742
4251
  }
3743
4252
  ],
3744
- "requestBody": {
3745
- "content": {
3746
- "application/json": {
3747
- "schema": {
3748
- "type": "object",
3749
- "properties": {
3750
- "url": {
3751
- "type": "string",
4253
+ "parameters": [
4254
+ {
4255
+ "schema": {
4256
+ "type": "string",
4257
+ "pattern": "^\\d{6,20}$",
4258
+ "example": "106540352242922",
4259
+ "description": "Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row)."
4260
+ },
4261
+ "required": true,
4262
+ "description": "Meta WhatsApp Business `phone_number_id` of the connected account that should send / own this resource. Discoverable via `GET /v1/accounts` (returned as `phone_number_id` on each row).",
4263
+ "name": "phone_number_id",
4264
+ "in": "path"
4265
+ }
4266
+ ],
4267
+ "responses": {
4268
+ "200": {
4269
+ "description": "Sync summary",
4270
+ "content": {
4271
+ "application/json": {
4272
+ "schema": {
4273
+ "$ref": "#/components/schemas/SyncTemplatesResponse"
4274
+ }
4275
+ }
4276
+ }
4277
+ },
4278
+ "400": {
4279
+ "description": "Validation failure",
4280
+ "content": {
4281
+ "application/json": {
4282
+ "schema": {
4283
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
4284
+ }
4285
+ }
4286
+ }
4287
+ },
4288
+ "401": {
4289
+ "description": "Authentication failure",
4290
+ "content": {
4291
+ "application/json": {
4292
+ "schema": {
4293
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
4294
+ }
4295
+ }
4296
+ }
4297
+ },
4298
+ "404": {
4299
+ "description": "Resource not found",
4300
+ "content": {
4301
+ "application/json": {
4302
+ "schema": {
4303
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
4304
+ }
4305
+ }
4306
+ }
4307
+ },
4308
+ "422": {
4309
+ "description": "Semantic failure (e.g. idempotency key reuse)",
4310
+ "content": {
4311
+ "application/json": {
4312
+ "schema": {
4313
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
4314
+ }
4315
+ }
4316
+ }
4317
+ },
4318
+ "429": {
4319
+ "description": "Rate limit exceeded",
4320
+ "content": {
4321
+ "application/json": {
4322
+ "schema": {
4323
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
4324
+ }
4325
+ }
4326
+ }
4327
+ },
4328
+ "500": {
4329
+ "description": "Internal server error",
4330
+ "content": {
4331
+ "application/json": {
4332
+ "schema": {
4333
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
4334
+ }
4335
+ }
4336
+ }
4337
+ },
4338
+ "502": {
4339
+ "description": "Upstream WhatsApp error",
4340
+ "content": {
4341
+ "application/json": {
4342
+ "schema": {
4343
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
4344
+ }
4345
+ }
4346
+ }
4347
+ }
4348
+ }
4349
+ }
4350
+ },
4351
+ "/webhook_subscriptions": {
4352
+ "post": {
4353
+ "tags": [
4354
+ "Webhook Subscriptions"
4355
+ ],
4356
+ "summary": "Create a webhook subscription",
4357
+ "description": "Create a webhook subscription. The response carries `initial_secret` ONCE — store it server-side immediately; Kirimdev cannot show it again.",
4358
+ "security": [
4359
+ {
4360
+ "bearerAuth": []
4361
+ }
4362
+ ],
4363
+ "requestBody": {
4364
+ "content": {
4365
+ "application/json": {
4366
+ "schema": {
4367
+ "type": "object",
4368
+ "properties": {
4369
+ "url": {
4370
+ "type": "string",
3752
4371
  "format": "uri"
3753
4372
  },
3754
4373
  "description": {
@@ -3765,7 +4384,13 @@
3765
4384
  "conversation.assigned",
3766
4385
  "conversation.closed",
3767
4386
  "contact.created",
3768
- "contact.updated"
4387
+ "contact.updated",
4388
+ "customer.created",
4389
+ "customer.updated",
4390
+ "customer.archived",
4391
+ "customer.onboarded",
4392
+ "customer.setup_link.created",
4393
+ "customer.setup_link.consumed"
3769
4394
  ]
3770
4395
  },
3771
4396
  "minItems": 1
@@ -4073,7 +4698,13 @@
4073
4698
  "conversation.assigned",
4074
4699
  "conversation.closed",
4075
4700
  "contact.created",
4076
- "contact.updated"
4701
+ "contact.updated",
4702
+ "customer.created",
4703
+ "customer.updated",
4704
+ "customer.archived",
4705
+ "customer.onboarded",
4706
+ "customer.setup_link.created",
4707
+ "customer.setup_link.consumed"
4077
4708
  ]
4078
4709
  },
4079
4710
  "minItems": 1
@@ -4319,7 +4950,7 @@
4319
4950
  }
4320
4951
  },
4321
4952
  "409": {
4322
- "description": "Conflict (e.g. webhook subscription disabled)",
4953
+ "description": "Conflict (e.g. webhook subscription disabled, setup link inactive)",
4323
4954
  "content": {
4324
4955
  "application/json": {
4325
4956
  "schema": {
@@ -4752,7 +5383,7 @@
4752
5383
  }
4753
5384
  },
4754
5385
  "409": {
4755
- "description": "Conflict (e.g. webhook subscription disabled)",
5386
+ "description": "Conflict (e.g. webhook subscription disabled, setup link inactive)",
4756
5387
  "content": {
4757
5388
  "application/json": {
4758
5389
  "schema": {
@@ -4877,7 +5508,7 @@
4877
5508
  }
4878
5509
  },
4879
5510
  "409": {
4880
- "description": "Conflict (e.g. webhook subscription disabled)",
5511
+ "description": "Conflict (e.g. webhook subscription disabled, setup link inactive)",
4881
5512
  "content": {
4882
5513
  "application/json": {
4883
5514
  "schema": {
@@ -7136,6 +7767,1053 @@
7136
7767
  }
7137
7768
  }
7138
7769
  }
7770
+ },
7771
+ "/customers": {
7772
+ "get": {
7773
+ "tags": [
7774
+ "Customers"
7775
+ ],
7776
+ "summary": "List customers",
7777
+ "description": "List end-customers (tenant-of-tenant) attached to the organization. Each customer can own one or more WhatsApp accounts via setup links. NOTE: a customer here is NOT a WhatsApp contact — see the `/{phone_number_id}/contacts` resource for those.",
7778
+ "security": [
7779
+ {
7780
+ "bearerAuth": []
7781
+ }
7782
+ ],
7783
+ "parameters": [
7784
+ {
7785
+ "schema": {
7786
+ "type": "string",
7787
+ "enum": [
7788
+ "pending",
7789
+ "active",
7790
+ "suspended",
7791
+ "archived"
7792
+ ]
7793
+ },
7794
+ "required": false,
7795
+ "name": "status",
7796
+ "in": "query"
7797
+ },
7798
+ {
7799
+ "schema": {
7800
+ "type": "string",
7801
+ "minLength": 1,
7802
+ "maxLength": 200
7803
+ },
7804
+ "required": false,
7805
+ "name": "search",
7806
+ "in": "query"
7807
+ },
7808
+ {
7809
+ "schema": {
7810
+ "type": "string",
7811
+ "pattern": "^\\d+$"
7812
+ },
7813
+ "required": false,
7814
+ "name": "limit",
7815
+ "in": "query"
7816
+ },
7817
+ {
7818
+ "schema": {
7819
+ "type": "string"
7820
+ },
7821
+ "required": false,
7822
+ "name": "cursor",
7823
+ "in": "query"
7824
+ }
7825
+ ],
7826
+ "responses": {
7827
+ "200": {
7828
+ "description": "Customer list",
7829
+ "content": {
7830
+ "application/json": {
7831
+ "schema": {
7832
+ "$ref": "#/components/schemas/ListCustomersResponse"
7833
+ }
7834
+ }
7835
+ }
7836
+ },
7837
+ "400": {
7838
+ "description": "Validation failure",
7839
+ "content": {
7840
+ "application/json": {
7841
+ "schema": {
7842
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
7843
+ }
7844
+ }
7845
+ }
7846
+ },
7847
+ "401": {
7848
+ "description": "Authentication failure",
7849
+ "content": {
7850
+ "application/json": {
7851
+ "schema": {
7852
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
7853
+ }
7854
+ }
7855
+ }
7856
+ },
7857
+ "402": {
7858
+ "description": "Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)",
7859
+ "content": {
7860
+ "application/json": {
7861
+ "schema": {
7862
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
7863
+ }
7864
+ }
7865
+ }
7866
+ },
7867
+ "429": {
7868
+ "description": "Rate limit exceeded",
7869
+ "content": {
7870
+ "application/json": {
7871
+ "schema": {
7872
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
7873
+ }
7874
+ }
7875
+ }
7876
+ },
7877
+ "500": {
7878
+ "description": "Internal server error",
7879
+ "content": {
7880
+ "application/json": {
7881
+ "schema": {
7882
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
7883
+ }
7884
+ }
7885
+ }
7886
+ }
7887
+ }
7888
+ },
7889
+ "post": {
7890
+ "tags": [
7891
+ "Customers"
7892
+ ],
7893
+ "summary": "Create a customer",
7894
+ "description": "Create a new end-customer. Starts in `pending` status; transitions to `active` when the first WhatsApp account is connected via a setup link.",
7895
+ "security": [
7896
+ {
7897
+ "bearerAuth": []
7898
+ }
7899
+ ],
7900
+ "requestBody": {
7901
+ "content": {
7902
+ "application/json": {
7903
+ "schema": {
7904
+ "type": "object",
7905
+ "properties": {
7906
+ "team_id": {
7907
+ "type": "string",
7908
+ "minLength": 1,
7909
+ "maxLength": 64
7910
+ },
7911
+ "name": {
7912
+ "type": "string",
7913
+ "minLength": 1,
7914
+ "maxLength": 200
7915
+ },
7916
+ "email": {
7917
+ "type": "string",
7918
+ "maxLength": 255,
7919
+ "format": "email"
7920
+ },
7921
+ "metadata": {
7922
+ "type": "object",
7923
+ "additionalProperties": {}
7924
+ }
7925
+ },
7926
+ "required": [
7927
+ "name"
7928
+ ]
7929
+ }
7930
+ }
7931
+ }
7932
+ },
7933
+ "responses": {
7934
+ "200": {
7935
+ "description": "Customer created",
7936
+ "content": {
7937
+ "application/json": {
7938
+ "schema": {
7939
+ "$ref": "#/components/schemas/CreateCustomerResponse"
7940
+ }
7941
+ }
7942
+ }
7943
+ },
7944
+ "400": {
7945
+ "description": "Validation failure",
7946
+ "content": {
7947
+ "application/json": {
7948
+ "schema": {
7949
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
7950
+ }
7951
+ }
7952
+ }
7953
+ },
7954
+ "401": {
7955
+ "description": "Authentication failure",
7956
+ "content": {
7957
+ "application/json": {
7958
+ "schema": {
7959
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
7960
+ }
7961
+ }
7962
+ }
7963
+ },
7964
+ "402": {
7965
+ "description": "Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)",
7966
+ "content": {
7967
+ "application/json": {
7968
+ "schema": {
7969
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
7970
+ }
7971
+ }
7972
+ }
7973
+ },
7974
+ "429": {
7975
+ "description": "Rate limit exceeded",
7976
+ "content": {
7977
+ "application/json": {
7978
+ "schema": {
7979
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
7980
+ }
7981
+ }
7982
+ }
7983
+ },
7984
+ "500": {
7985
+ "description": "Internal server error",
7986
+ "content": {
7987
+ "application/json": {
7988
+ "schema": {
7989
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
7990
+ }
7991
+ }
7992
+ }
7993
+ }
7994
+ }
7995
+ }
7996
+ },
7997
+ "/customers/{id}": {
7998
+ "get": {
7999
+ "tags": [
8000
+ "Customers"
8001
+ ],
8002
+ "summary": "Fetch a customer by id",
8003
+ "security": [
8004
+ {
8005
+ "bearerAuth": []
8006
+ }
8007
+ ],
8008
+ "parameters": [
8009
+ {
8010
+ "schema": {
8011
+ "type": "string",
8012
+ "pattern": "^cus_[0-9A-HJKMNP-TV-Z]{26}$"
8013
+ },
8014
+ "required": true,
8015
+ "name": "id",
8016
+ "in": "path"
8017
+ }
8018
+ ],
8019
+ "responses": {
8020
+ "200": {
8021
+ "description": "Customer resource (includes attached WhatsApp accounts)",
8022
+ "content": {
8023
+ "application/json": {
8024
+ "schema": {
8025
+ "$ref": "#/components/schemas/GetCustomerResponse"
8026
+ }
8027
+ }
8028
+ }
8029
+ },
8030
+ "400": {
8031
+ "description": "Validation failure",
8032
+ "content": {
8033
+ "application/json": {
8034
+ "schema": {
8035
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8036
+ }
8037
+ }
8038
+ }
8039
+ },
8040
+ "401": {
8041
+ "description": "Authentication failure",
8042
+ "content": {
8043
+ "application/json": {
8044
+ "schema": {
8045
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8046
+ }
8047
+ }
8048
+ }
8049
+ },
8050
+ "402": {
8051
+ "description": "Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)",
8052
+ "content": {
8053
+ "application/json": {
8054
+ "schema": {
8055
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8056
+ }
8057
+ }
8058
+ }
8059
+ },
8060
+ "404": {
8061
+ "description": "Resource not found",
8062
+ "content": {
8063
+ "application/json": {
8064
+ "schema": {
8065
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8066
+ }
8067
+ }
8068
+ }
8069
+ },
8070
+ "429": {
8071
+ "description": "Rate limit exceeded",
8072
+ "content": {
8073
+ "application/json": {
8074
+ "schema": {
8075
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8076
+ }
8077
+ }
8078
+ }
8079
+ },
8080
+ "500": {
8081
+ "description": "Internal server error",
8082
+ "content": {
8083
+ "application/json": {
8084
+ "schema": {
8085
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8086
+ }
8087
+ }
8088
+ }
8089
+ }
8090
+ }
8091
+ },
8092
+ "patch": {
8093
+ "tags": [
8094
+ "Customers"
8095
+ ],
8096
+ "summary": "Update a customer",
8097
+ "security": [
8098
+ {
8099
+ "bearerAuth": []
8100
+ }
8101
+ ],
8102
+ "parameters": [
8103
+ {
8104
+ "schema": {
8105
+ "type": "string",
8106
+ "pattern": "^cus_[0-9A-HJKMNP-TV-Z]{26}$"
8107
+ },
8108
+ "required": true,
8109
+ "name": "id",
8110
+ "in": "path"
8111
+ }
8112
+ ],
8113
+ "requestBody": {
8114
+ "content": {
8115
+ "application/json": {
8116
+ "schema": {
8117
+ "type": "object",
8118
+ "properties": {
8119
+ "name": {
8120
+ "type": "string",
8121
+ "minLength": 1,
8122
+ "maxLength": 200
8123
+ },
8124
+ "email": {
8125
+ "type": [
8126
+ "string",
8127
+ "null"
8128
+ ],
8129
+ "maxLength": 255,
8130
+ "format": "email"
8131
+ },
8132
+ "metadata": {
8133
+ "type": [
8134
+ "object",
8135
+ "null"
8136
+ ],
8137
+ "additionalProperties": {}
8138
+ },
8139
+ "status": {
8140
+ "type": "string",
8141
+ "enum": [
8142
+ "pending",
8143
+ "active",
8144
+ "suspended"
8145
+ ]
8146
+ }
8147
+ }
8148
+ }
8149
+ }
8150
+ }
8151
+ },
8152
+ "responses": {
8153
+ "200": {
8154
+ "description": "Updated customer",
8155
+ "content": {
8156
+ "application/json": {
8157
+ "schema": {
8158
+ "$ref": "#/components/schemas/UpdateCustomerResponse"
8159
+ }
8160
+ }
8161
+ }
8162
+ },
8163
+ "400": {
8164
+ "description": "Validation failure",
8165
+ "content": {
8166
+ "application/json": {
8167
+ "schema": {
8168
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8169
+ }
8170
+ }
8171
+ }
8172
+ },
8173
+ "401": {
8174
+ "description": "Authentication failure",
8175
+ "content": {
8176
+ "application/json": {
8177
+ "schema": {
8178
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8179
+ }
8180
+ }
8181
+ }
8182
+ },
8183
+ "402": {
8184
+ "description": "Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)",
8185
+ "content": {
8186
+ "application/json": {
8187
+ "schema": {
8188
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8189
+ }
8190
+ }
8191
+ }
8192
+ },
8193
+ "404": {
8194
+ "description": "Resource not found",
8195
+ "content": {
8196
+ "application/json": {
8197
+ "schema": {
8198
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8199
+ }
8200
+ }
8201
+ }
8202
+ },
8203
+ "429": {
8204
+ "description": "Rate limit exceeded",
8205
+ "content": {
8206
+ "application/json": {
8207
+ "schema": {
8208
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8209
+ }
8210
+ }
8211
+ }
8212
+ },
8213
+ "500": {
8214
+ "description": "Internal server error",
8215
+ "content": {
8216
+ "application/json": {
8217
+ "schema": {
8218
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8219
+ }
8220
+ }
8221
+ }
8222
+ }
8223
+ }
8224
+ },
8225
+ "delete": {
8226
+ "tags": [
8227
+ "Customers"
8228
+ ],
8229
+ "summary": "Archive a customer",
8230
+ "description": "Soft-archives the customer. WhatsApp accounts previously assigned remain in the database with `customer_id` unchanged — message history is never destroyed.",
8231
+ "security": [
8232
+ {
8233
+ "bearerAuth": []
8234
+ }
8235
+ ],
8236
+ "parameters": [
8237
+ {
8238
+ "schema": {
8239
+ "type": "string",
8240
+ "pattern": "^cus_[0-9A-HJKMNP-TV-Z]{26}$"
8241
+ },
8242
+ "required": true,
8243
+ "name": "id",
8244
+ "in": "path"
8245
+ }
8246
+ ],
8247
+ "responses": {
8248
+ "200": {
8249
+ "description": "Archived",
8250
+ "content": {
8251
+ "application/json": {
8252
+ "schema": {
8253
+ "$ref": "#/components/schemas/ArchiveCustomerResponse"
8254
+ }
8255
+ }
8256
+ }
8257
+ },
8258
+ "400": {
8259
+ "description": "Validation failure",
8260
+ "content": {
8261
+ "application/json": {
8262
+ "schema": {
8263
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8264
+ }
8265
+ }
8266
+ }
8267
+ },
8268
+ "401": {
8269
+ "description": "Authentication failure",
8270
+ "content": {
8271
+ "application/json": {
8272
+ "schema": {
8273
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8274
+ }
8275
+ }
8276
+ }
8277
+ },
8278
+ "402": {
8279
+ "description": "Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)",
8280
+ "content": {
8281
+ "application/json": {
8282
+ "schema": {
8283
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8284
+ }
8285
+ }
8286
+ }
8287
+ },
8288
+ "404": {
8289
+ "description": "Resource not found",
8290
+ "content": {
8291
+ "application/json": {
8292
+ "schema": {
8293
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8294
+ }
8295
+ }
8296
+ }
8297
+ },
8298
+ "429": {
8299
+ "description": "Rate limit exceeded",
8300
+ "content": {
8301
+ "application/json": {
8302
+ "schema": {
8303
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8304
+ }
8305
+ }
8306
+ }
8307
+ },
8308
+ "500": {
8309
+ "description": "Internal server error",
8310
+ "content": {
8311
+ "application/json": {
8312
+ "schema": {
8313
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8314
+ }
8315
+ }
8316
+ }
8317
+ }
8318
+ }
8319
+ }
8320
+ },
8321
+ "/customers/{id}/setup_links": {
8322
+ "get": {
8323
+ "tags": [
8324
+ "Customers"
8325
+ ],
8326
+ "summary": "List setup links for a customer",
8327
+ "description": "Returns up to the 50 most-recent setup links — token plaintext is NEVER returned here (only at create time). Optional `status` query filters to `active` / `consumed` / `expired` / `revoked`.",
8328
+ "security": [
8329
+ {
8330
+ "bearerAuth": []
8331
+ }
8332
+ ],
8333
+ "parameters": [
8334
+ {
8335
+ "schema": {
8336
+ "type": "string",
8337
+ "pattern": "^cus_[0-9A-HJKMNP-TV-Z]{26}$"
8338
+ },
8339
+ "required": true,
8340
+ "name": "id",
8341
+ "in": "path"
8342
+ },
8343
+ {
8344
+ "schema": {
8345
+ "type": "string",
8346
+ "enum": [
8347
+ "active",
8348
+ "consumed",
8349
+ "expired",
8350
+ "revoked"
8351
+ ]
8352
+ },
8353
+ "required": false,
8354
+ "name": "status",
8355
+ "in": "query"
8356
+ }
8357
+ ],
8358
+ "responses": {
8359
+ "200": {
8360
+ "description": "Setup link list",
8361
+ "content": {
8362
+ "application/json": {
8363
+ "schema": {
8364
+ "$ref": "#/components/schemas/ListCustomerSetupLinksResponse"
8365
+ }
8366
+ }
8367
+ }
8368
+ },
8369
+ "400": {
8370
+ "description": "Validation failure",
8371
+ "content": {
8372
+ "application/json": {
8373
+ "schema": {
8374
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8375
+ }
8376
+ }
8377
+ }
8378
+ },
8379
+ "401": {
8380
+ "description": "Authentication failure",
8381
+ "content": {
8382
+ "application/json": {
8383
+ "schema": {
8384
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8385
+ }
8386
+ }
8387
+ }
8388
+ },
8389
+ "402": {
8390
+ "description": "Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)",
8391
+ "content": {
8392
+ "application/json": {
8393
+ "schema": {
8394
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8395
+ }
8396
+ }
8397
+ }
8398
+ },
8399
+ "404": {
8400
+ "description": "Resource not found",
8401
+ "content": {
8402
+ "application/json": {
8403
+ "schema": {
8404
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8405
+ }
8406
+ }
8407
+ }
8408
+ },
8409
+ "429": {
8410
+ "description": "Rate limit exceeded",
8411
+ "content": {
8412
+ "application/json": {
8413
+ "schema": {
8414
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8415
+ }
8416
+ }
8417
+ }
8418
+ },
8419
+ "500": {
8420
+ "description": "Internal server error",
8421
+ "content": {
8422
+ "application/json": {
8423
+ "schema": {
8424
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8425
+ }
8426
+ }
8427
+ }
8428
+ }
8429
+ }
8430
+ },
8431
+ "post": {
8432
+ "tags": [
8433
+ "Customers"
8434
+ ],
8435
+ "summary": "Generate a setup link",
8436
+ "description": "Creates a one-time setup link the end-customer can use to complete Meta Embedded Signup. The plaintext token and full setup URL are returned EXACTLY ONCE — store them immediately.",
8437
+ "security": [
8438
+ {
8439
+ "bearerAuth": []
8440
+ }
8441
+ ],
8442
+ "parameters": [
8443
+ {
8444
+ "schema": {
8445
+ "type": "string",
8446
+ "pattern": "^cus_[0-9A-HJKMNP-TV-Z]{26}$"
8447
+ },
8448
+ "required": true,
8449
+ "name": "id",
8450
+ "in": "path"
8451
+ }
8452
+ ],
8453
+ "requestBody": {
8454
+ "content": {
8455
+ "application/json": {
8456
+ "schema": {
8457
+ "type": "object",
8458
+ "properties": {
8459
+ "expires_in_hours": {
8460
+ "type": "integer",
8461
+ "minimum": 1,
8462
+ "maximum": 720
8463
+ },
8464
+ "success_redirect_url": {
8465
+ "type": "string",
8466
+ "maxLength": 2048,
8467
+ "format": "uri"
8468
+ },
8469
+ "failure_redirect_url": {
8470
+ "type": "string",
8471
+ "maxLength": 2048,
8472
+ "format": "uri"
8473
+ }
8474
+ }
8475
+ }
8476
+ }
8477
+ }
8478
+ },
8479
+ "responses": {
8480
+ "200": {
8481
+ "description": "Setup link created (token returned ONCE)",
8482
+ "content": {
8483
+ "application/json": {
8484
+ "schema": {
8485
+ "$ref": "#/components/schemas/CreateCustomerSetupLinkResponse"
8486
+ }
8487
+ }
8488
+ }
8489
+ },
8490
+ "400": {
8491
+ "description": "Validation failure",
8492
+ "content": {
8493
+ "application/json": {
8494
+ "schema": {
8495
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8496
+ }
8497
+ }
8498
+ }
8499
+ },
8500
+ "401": {
8501
+ "description": "Authentication failure",
8502
+ "content": {
8503
+ "application/json": {
8504
+ "schema": {
8505
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8506
+ }
8507
+ }
8508
+ }
8509
+ },
8510
+ "402": {
8511
+ "description": "Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)",
8512
+ "content": {
8513
+ "application/json": {
8514
+ "schema": {
8515
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8516
+ }
8517
+ }
8518
+ }
8519
+ },
8520
+ "404": {
8521
+ "description": "Resource not found",
8522
+ "content": {
8523
+ "application/json": {
8524
+ "schema": {
8525
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8526
+ }
8527
+ }
8528
+ }
8529
+ },
8530
+ "429": {
8531
+ "description": "Rate limit exceeded",
8532
+ "content": {
8533
+ "application/json": {
8534
+ "schema": {
8535
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8536
+ }
8537
+ }
8538
+ }
8539
+ },
8540
+ "500": {
8541
+ "description": "Internal server error",
8542
+ "content": {
8543
+ "application/json": {
8544
+ "schema": {
8545
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8546
+ }
8547
+ }
8548
+ }
8549
+ }
8550
+ }
8551
+ }
8552
+ },
8553
+ "/customers/{id}/setup_links/{link_id}": {
8554
+ "patch": {
8555
+ "tags": [
8556
+ "Customers"
8557
+ ],
8558
+ "summary": "Update redirect URLs on an active setup link",
8559
+ "description": "Recover from a typo in `success_redirect_url` / `failure_redirect_url` without revoking and regenerating the link. Only works while `status = active`; pass `null` to clear a redirect.",
8560
+ "security": [
8561
+ {
8562
+ "bearerAuth": []
8563
+ }
8564
+ ],
8565
+ "parameters": [
8566
+ {
8567
+ "schema": {
8568
+ "type": "string",
8569
+ "pattern": "^cus_[0-9A-HJKMNP-TV-Z]{26}$"
8570
+ },
8571
+ "required": true,
8572
+ "name": "id",
8573
+ "in": "path"
8574
+ },
8575
+ {
8576
+ "schema": {
8577
+ "type": "string",
8578
+ "pattern": "^csl_[0-9A-HJKMNP-TV-Z]{26}$"
8579
+ },
8580
+ "required": true,
8581
+ "name": "link_id",
8582
+ "in": "path"
8583
+ }
8584
+ ],
8585
+ "requestBody": {
8586
+ "content": {
8587
+ "application/json": {
8588
+ "schema": {
8589
+ "type": "object",
8590
+ "properties": {
8591
+ "success_redirect_url": {
8592
+ "anyOf": [
8593
+ {
8594
+ "type": "string",
8595
+ "maxLength": 2048,
8596
+ "format": "uri"
8597
+ },
8598
+ {
8599
+ "type": "null"
8600
+ }
8601
+ ]
8602
+ },
8603
+ "failure_redirect_url": {
8604
+ "anyOf": [
8605
+ {
8606
+ "type": "string",
8607
+ "maxLength": 2048,
8608
+ "format": "uri"
8609
+ },
8610
+ {
8611
+ "type": "null"
8612
+ }
8613
+ ]
8614
+ }
8615
+ }
8616
+ }
8617
+ }
8618
+ }
8619
+ },
8620
+ "responses": {
8621
+ "200": {
8622
+ "description": "Updated setup link",
8623
+ "content": {
8624
+ "application/json": {
8625
+ "schema": {
8626
+ "$ref": "#/components/schemas/UpdateCustomerSetupLinkResponse"
8627
+ }
8628
+ }
8629
+ }
8630
+ },
8631
+ "400": {
8632
+ "description": "Validation failure",
8633
+ "content": {
8634
+ "application/json": {
8635
+ "schema": {
8636
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8637
+ }
8638
+ }
8639
+ }
8640
+ },
8641
+ "401": {
8642
+ "description": "Authentication failure",
8643
+ "content": {
8644
+ "application/json": {
8645
+ "schema": {
8646
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8647
+ }
8648
+ }
8649
+ }
8650
+ },
8651
+ "402": {
8652
+ "description": "Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)",
8653
+ "content": {
8654
+ "application/json": {
8655
+ "schema": {
8656
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8657
+ }
8658
+ }
8659
+ }
8660
+ },
8661
+ "404": {
8662
+ "description": "Resource not found",
8663
+ "content": {
8664
+ "application/json": {
8665
+ "schema": {
8666
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8667
+ }
8668
+ }
8669
+ }
8670
+ },
8671
+ "409": {
8672
+ "description": "Conflict (e.g. webhook subscription disabled, setup link inactive)",
8673
+ "content": {
8674
+ "application/json": {
8675
+ "schema": {
8676
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8677
+ }
8678
+ }
8679
+ }
8680
+ },
8681
+ "429": {
8682
+ "description": "Rate limit exceeded",
8683
+ "content": {
8684
+ "application/json": {
8685
+ "schema": {
8686
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8687
+ }
8688
+ }
8689
+ }
8690
+ },
8691
+ "500": {
8692
+ "description": "Internal server error",
8693
+ "content": {
8694
+ "application/json": {
8695
+ "schema": {
8696
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8697
+ }
8698
+ }
8699
+ }
8700
+ }
8701
+ }
8702
+ },
8703
+ "delete": {
8704
+ "tags": [
8705
+ "Customers"
8706
+ ],
8707
+ "summary": "Revoke a setup link",
8708
+ "description": "Revoke a still-active link. Already-consumed or already-revoked links return `409`.",
8709
+ "security": [
8710
+ {
8711
+ "bearerAuth": []
8712
+ }
8713
+ ],
8714
+ "parameters": [
8715
+ {
8716
+ "schema": {
8717
+ "type": "string",
8718
+ "pattern": "^cus_[0-9A-HJKMNP-TV-Z]{26}$"
8719
+ },
8720
+ "required": true,
8721
+ "name": "id",
8722
+ "in": "path"
8723
+ },
8724
+ {
8725
+ "schema": {
8726
+ "type": "string",
8727
+ "pattern": "^csl_[0-9A-HJKMNP-TV-Z]{26}$"
8728
+ },
8729
+ "required": true,
8730
+ "name": "link_id",
8731
+ "in": "path"
8732
+ }
8733
+ ],
8734
+ "responses": {
8735
+ "200": {
8736
+ "description": "Revoked",
8737
+ "content": {
8738
+ "application/json": {
8739
+ "schema": {
8740
+ "$ref": "#/components/schemas/RevokeCustomerSetupLinkResponse"
8741
+ }
8742
+ }
8743
+ }
8744
+ },
8745
+ "400": {
8746
+ "description": "Validation failure",
8747
+ "content": {
8748
+ "application/json": {
8749
+ "schema": {
8750
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8751
+ }
8752
+ }
8753
+ }
8754
+ },
8755
+ "401": {
8756
+ "description": "Authentication failure",
8757
+ "content": {
8758
+ "application/json": {
8759
+ "schema": {
8760
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8761
+ }
8762
+ }
8763
+ }
8764
+ },
8765
+ "402": {
8766
+ "description": "Plan / quota / subscription gate (e.g. feature_not_entitled, quota_exceeded, subscription_inactive)",
8767
+ "content": {
8768
+ "application/json": {
8769
+ "schema": {
8770
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8771
+ }
8772
+ }
8773
+ }
8774
+ },
8775
+ "404": {
8776
+ "description": "Resource not found",
8777
+ "content": {
8778
+ "application/json": {
8779
+ "schema": {
8780
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8781
+ }
8782
+ }
8783
+ }
8784
+ },
8785
+ "409": {
8786
+ "description": "Conflict (e.g. webhook subscription disabled, setup link inactive)",
8787
+ "content": {
8788
+ "application/json": {
8789
+ "schema": {
8790
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8791
+ }
8792
+ }
8793
+ }
8794
+ },
8795
+ "429": {
8796
+ "description": "Rate limit exceeded",
8797
+ "content": {
8798
+ "application/json": {
8799
+ "schema": {
8800
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8801
+ }
8802
+ }
8803
+ }
8804
+ },
8805
+ "500": {
8806
+ "description": "Internal server error",
8807
+ "content": {
8808
+ "application/json": {
8809
+ "schema": {
8810
+ "$ref": "#/components/schemas/ApiErrorEnvelope"
8811
+ }
8812
+ }
8813
+ }
8814
+ }
8815
+ }
8816
+ }
7139
8817
  }
7140
8818
  },
7141
8819
  "webhooks": {}