George Lambert
b4150c8250
Compose-ready workspace: packages/zappier (rate card, portal, Stripe), packages/verae-zapier-middleware (timestamp + NATS), packages/verae-zapier (CLI app), vendor/zapier-platform, and research/zapier vendor corpus. Gate 0 structure checks pass. Product code and research are not yet wired.
505 lines
18 KiB
YAML
505 lines
18 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: Powered by Zapier Promotions API
|
|
version: promotions
|
|
description: The API to define promotions, powered by Zapier. See https://docs.zapier.com/powered-by-zapier/introduction for more information.
|
|
contact:
|
|
name: Partner Sharing
|
|
paths:
|
|
/v2/promotions:
|
|
post:
|
|
operationId: root_create
|
|
description: |-
|
|
Enrolls an account into an existing promotion.
|
|
|
|
Endpoint available to Partners only.
|
|
The request must be authenticated by an [access token](https://docs.zapier.com/powered-by-zapier/api-reference/authentication#retrieving-a-user-access-token)
|
|
that the user has granted to the Partner for the account.
|
|
|
|
The `enrollment_id`, returned after successfully enrolling a user,
|
|
**must** be stored by the partner in order to [retrieve](https://docs.zapier.com/powered-by-zapier/api-reference/promotions/get-enrollment)
|
|
or [delete](https://docs.zapier.com/powered-by-zapier/api-reference/promotions/delete-enrollment) the enrollment.
|
|
|
|
#### OAuth
|
|
|
|
This endpoint requires the `promotions:write` OAuth scope.
|
|
summary: Create a promotion enrollment
|
|
tags:
|
|
- Promotions
|
|
- Experimental
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromotionEnrollment'
|
|
examples:
|
|
EnrollInAPromotion:
|
|
value:
|
|
promotion_id: promo_12345
|
|
summary: Enroll in a promotion
|
|
required: true
|
|
security:
|
|
- OAuth:
|
|
- promotions:write
|
|
responses:
|
|
'201':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromotionEnrollmentResponse'
|
|
description: Successful Enrollment
|
|
'404':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromotionErrorResponse'
|
|
examples:
|
|
'404':
|
|
value:
|
|
errors:
|
|
- status: '404'
|
|
code: promotion_not_found
|
|
title: Promotion Not Found
|
|
detail: The requested promotion was not found. The specified promotion_id may be invalid.
|
|
description: 404 Not Found
|
|
'409':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromotionErrorResponse'
|
|
examples:
|
|
Conflict:
|
|
value:
|
|
errors:
|
|
- status: '409'
|
|
code: already_enrolled
|
|
title: Already Enrolled
|
|
detail: The provided account is already enrolled in the specified promotion.
|
|
description: Conflict - User is already enrolled in this promotion
|
|
'429':
|
|
headers:
|
|
Retry-After:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: Indicates when to retry the request
|
|
X-RateLimit-Limit:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: The maximum number of requests you're permitted to make per hour.
|
|
X-RateLimit-Remaining:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: The number of requests remaining in the current rate limit window.
|
|
X-RateLimit-Reset:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: The time at which the current rate limit window resets in UTC epoch seconds.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromotionErrorResponse'
|
|
description: ''
|
|
'503':
|
|
headers:
|
|
Retry-After:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: Indicates when to retry the request
|
|
X-RateLimit-Limit:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: The maximum number of requests you're permitted to make per hour.
|
|
X-RateLimit-Remaining:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: The number of requests remaining in the current rate limit window.
|
|
X-RateLimit-Reset:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: The time at which the current rate limit window resets in UTC epoch seconds.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromotionErrorResponse'
|
|
description: ''
|
|
'403':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromotionErrorResponse'
|
|
examples:
|
|
Forbidden:
|
|
value:
|
|
errors:
|
|
- status: '403'
|
|
code: permission_denied
|
|
title: Permission Denied
|
|
detail: You do not have permission to perform this action.
|
|
description: Forbidden - User lacks permission to access this location
|
|
'401':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromotionErrorResponse'
|
|
examples:
|
|
Access:
|
|
value:
|
|
errors:
|
|
- status: '401'
|
|
code: not_authenticated
|
|
title: User Not Authenticated
|
|
detail: User must be authenticated to access this resource. No valid user access token was provided.
|
|
description: 'Access denied: User does not have permission for enrollment_id: enroll_67890'
|
|
/v2/promotions/{enrollment_id}:
|
|
get:
|
|
operationId: root_retrieve
|
|
description: |-
|
|
Retrieve promotion enrollment details by enrollment ID.
|
|
|
|
Endpoint available to Partners only.
|
|
The request must be authenticated by a user access token
|
|
that the user has granted to the Partner for the account.
|
|
|
|
#### OAuth
|
|
|
|
This endpoint requires the `promotions:read` OAuth scope.
|
|
parameters:
|
|
- in: path
|
|
name: enrollment_id
|
|
schema:
|
|
type: string
|
|
required: true
|
|
tags:
|
|
- Promotions
|
|
- Experimental
|
|
security:
|
|
- OAuth:
|
|
- promotions:read
|
|
responses:
|
|
'200':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromotionDetail'
|
|
examples:
|
|
GetPromotionDetails:
|
|
value:
|
|
promotion_id: test_promo
|
|
enrollment_date: '2026-04-28T00:00:00Z'
|
|
expiration_date: '2026-07-26T23:59:59Z'
|
|
task_limit_per_month: 5
|
|
tasks_used_this_month: 0
|
|
status: enrolled
|
|
summary: Get Promotion Details
|
|
description: Succcessful retrieval of promotion details
|
|
'404':
|
|
description: No response body
|
|
'429':
|
|
headers:
|
|
Retry-After:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: Indicates when to retry the request
|
|
X-RateLimit-Limit:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: The maximum number of requests you're permitted to make per hour.
|
|
X-RateLimit-Remaining:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: The number of requests remaining in the current rate limit window.
|
|
X-RateLimit-Reset:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: The time at which the current rate limit window resets in UTC epoch seconds.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromotionErrorResponse'
|
|
description: ''
|
|
'503':
|
|
headers:
|
|
Retry-After:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: Indicates when to retry the request
|
|
X-RateLimit-Limit:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: The maximum number of requests you're permitted to make per hour.
|
|
X-RateLimit-Remaining:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: The number of requests remaining in the current rate limit window.
|
|
X-RateLimit-Reset:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: The time at which the current rate limit window resets in UTC epoch seconds.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromotionErrorResponse'
|
|
description: ''
|
|
'403':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromotionErrorResponse'
|
|
examples:
|
|
Forbidden:
|
|
value:
|
|
errors:
|
|
- status: '403'
|
|
code: permission_denied
|
|
title: Permission Denied
|
|
detail: You do not have permission to perform this action.
|
|
description: Forbidden - User lacks permission to access this location
|
|
'401':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromotionErrorResponse'
|
|
examples:
|
|
Access:
|
|
value:
|
|
errors:
|
|
- status: '401'
|
|
code: not_authenticated
|
|
title: User Not Authenticated
|
|
detail: User must be authenticated to access this resource. No valid user access token was provided.
|
|
description: 'Access denied: User does not have permission for enrollment_id: enroll_67890'
|
|
delete:
|
|
operationId: root_destroy
|
|
description: |-
|
|
Unenroll an account from a promotion.
|
|
|
|
Endpoint available to Partners only.
|
|
The request must be authenticated by an app access token the
|
|
Partner has received using the Client Credentials flow.
|
|
|
|
#### OAuth
|
|
|
|
This endpoint requires the `promotions:write` OAuth scope.
|
|
parameters:
|
|
- in: path
|
|
name: enrollment_id
|
|
schema:
|
|
type: string
|
|
required: true
|
|
tags:
|
|
- Promotions
|
|
- Experimental
|
|
security:
|
|
- OAuth:
|
|
- promotions:write
|
|
responses:
|
|
'204':
|
|
description: No response body
|
|
'429':
|
|
headers:
|
|
Retry-After:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: Indicates when to retry the request
|
|
X-RateLimit-Limit:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: The maximum number of requests you're permitted to make per hour.
|
|
X-RateLimit-Remaining:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: The number of requests remaining in the current rate limit window.
|
|
X-RateLimit-Reset:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: The time at which the current rate limit window resets in UTC epoch seconds.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromotionErrorResponse'
|
|
description: ''
|
|
'503':
|
|
headers:
|
|
Retry-After:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: Indicates when to retry the request
|
|
X-RateLimit-Limit:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: The maximum number of requests you're permitted to make per hour.
|
|
X-RateLimit-Remaining:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: The number of requests remaining in the current rate limit window.
|
|
X-RateLimit-Reset:
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
description: The time at which the current rate limit window resets in UTC epoch seconds.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromotionErrorResponse'
|
|
description: ''
|
|
'403':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromotionErrorResponse'
|
|
examples:
|
|
Forbidden:
|
|
value:
|
|
errors:
|
|
- status: '403'
|
|
code: permission_denied
|
|
title: Permission Denied
|
|
detail: You do not have permission to perform this action.
|
|
description: Forbidden - User lacks permission to access this location
|
|
'401':
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromotionErrorResponse'
|
|
examples:
|
|
Access:
|
|
value:
|
|
errors:
|
|
- status: '401'
|
|
code: not_authenticated
|
|
title: User Not Authenticated
|
|
detail: User must be authenticated to access this resource. No valid user access token was provided.
|
|
description: 'Access denied: User does not have permission for enrollment_id: enroll_67890'
|
|
components:
|
|
schemas:
|
|
PromotionDetail:
|
|
type: object
|
|
description: Succcessful retrieval of promotion details
|
|
properties:
|
|
promotion_id:
|
|
type: string
|
|
description: The unique identifier for the promotion
|
|
enrollment_date:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
format: date-time
|
|
description: Date and time of enrollment
|
|
expiration_date:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
format: date-time
|
|
description: Date and time when the promotion expires
|
|
task_limit_per_month:
|
|
type:
|
|
- integer
|
|
- 'null'
|
|
description: Maximum number of tasks allowed per monthly billing cycle
|
|
tasks_used_this_month:
|
|
type: integer
|
|
description: Number of tasks already used this monthly billing cycle (may not align with calendar month)
|
|
status:
|
|
type: string
|
|
description: Current status of the enrollment
|
|
required:
|
|
- enrollment_date
|
|
- expiration_date
|
|
- promotion_id
|
|
- status
|
|
- task_limit_per_month
|
|
- tasks_used_this_month
|
|
PromotionEnrollment:
|
|
type: object
|
|
properties:
|
|
promotion_id:
|
|
type: string
|
|
description: The unique identifier for the promotions
|
|
required:
|
|
- promotion_id
|
|
PromotionEnrollmentResponse:
|
|
type: object
|
|
description: Successful Enrollment
|
|
properties:
|
|
enrollment_id:
|
|
type: string
|
|
description: The unique identifier for the enrollment. This must be stored by partners.
|
|
required:
|
|
- enrollment_id
|
|
PromotionError:
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
description: HTTP status code of the error
|
|
code:
|
|
type: string
|
|
description: Machine-readable error code
|
|
title:
|
|
type: string
|
|
description: Human-readable error title
|
|
detail:
|
|
type: string
|
|
description: Detailed description of the error
|
|
required:
|
|
- code
|
|
- detail
|
|
- status
|
|
- title
|
|
PromotionErrorResponse:
|
|
type: object
|
|
properties:
|
|
errors:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/PromotionError'
|
|
description: Errors encountered processing the request
|
|
required:
|
|
- errors
|
|
securitySchemes:
|
|
OAuth:
|
|
type: oauth2
|
|
description: The user access token for the user you would like to enroll. See our [OAuth2 authentication documentation](https://docs.zapier.com/powered-by-zapier/api-reference/authentication#retrieving-a-user-access-token).
|
|
flows:
|
|
authorizationCode:
|
|
authorizationUrl: https://zapier.com/oauth/authorize/
|
|
tokenUrl: https://zapier.com/oauth/token/
|
|
refreshUrl: https://zapier.com/oauth/token/
|
|
scopes:
|
|
promotions:write: Enroll or unenroll accounts into promotions
|
|
promotions:read: View usage of promotions you manage on an account
|
|
clientCredentials:
|
|
tokenUrl: /oauth/token
|
|
scopes:
|
|
promotions:write: Unenroll accounts from promotions
|
|
servers:
|
|
- url: https://api.zapier.com
|
|
description: Production
|
|
tags:
|
|
- name: Promotions
|
|
description: Operations related to managing Promotions
|
|
- name: Experimental
|
|
description: Operations that are not to be considered finalized, and are subject to change
|