Overflow Subscriptions API
The Subscriptions API from Overflow — 3 operation(s) for subscriptions.
OpenAPI Specification
openapi: 3.0.0
info:
title: Overflow Open Campaigns Subscriptions API
description: '
The documentation for the Overflow Open APIs.
To access the OpenAPI spec in JSON/YAML format, navigate to:
* `/api/docs/openapi.json`
* `/api/docs/openapi.yaml`
'
version: '3.0'
contact: {}
servers:
- url: https://server.stage.overflow.co
description: API server
tags:
- name: Subscriptions
paths:
/api/v3/subscriptions/{donorId}:
post:
description: Creates a new recurring donation subscription for a donor.
operationId: OpenApiSubscriptionsController_createSubscription
parameters:
- name: donorId
required: true
in: path
description: The Id of the donor to create the subscription for.
schema:
example: 2ea1ae03ca521e437db76d76
type: string
requestBody:
required: true
description: Subscription creation details
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSubscriptionRequest'
responses:
'201':
description: Subscription created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSubscriptionResponse'
'400':
description: Invalid request parameters
'404':
description: Resource not found
'500':
description: Internal server error
security:
- ClientId: []
ApiKey: []
summary: Create Subscription
tags:
- Subscriptions
get:
description: Returns all subscriptions for the specified donor.
operationId: OpenApiSubscriptionsController_getSubscriptionsByDonorProfile
parameters:
- name: donorId
required: true
in: path
schema:
$ref: '#/components/schemas/NonprofitDonorProfileEntity'
- name: limit
required: false
in: query
description: The number of subscriptions to return.
schema:
minimum: 1
maximum: 100
default: 25
type: number
- name: maximumUpdatedDate
required: false
in: query
description: The maximum updated date of the subscriptions to return.
schema:
format: date-time
example: '2025-02-01'
type: string
- name: minimumUpdatedDate
required: false
in: query
description: The minimum updated date of the subscriptions to return.
schema:
format: date-time
example: '2025-01-01'
type: string
- name: page
required: false
in: query
description: The page number of the subscriptions to return.
schema:
minimum: 1
default: 1
type: number
- name: status
required: false
in: query
description: The status of the subscriptions to return.
schema:
example:
- active
type: array
items:
type: string
enum:
- active
- failed
- inactive
- paused
- pending
- recreated
- name: locationIds
required: false
in: query
description: Filter subscriptions by location Ids.
schema:
example:
- 6710f34fd5061afeec3eab57
type: array
items:
type: string
- name: sortBy
required: false
in: query
description: The field to sort the subscriptions by.
schema:
default: createdAt
example: createdAt
enum:
- amount
- createdAt
- frequency
- nextContributionAt
type: string
- name: sortDirection
required: false
in: query
description: The direction to sort the subscriptions by.
schema:
default: DESC
example: DESC
enum:
- ASC
- DESC
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetSubscriptionsResponse'
'400':
description: Donor does not belong to the nonprofit
'404':
description: Donor profile does not exist
security:
- ClientId: []
ApiKey: []
summary: Get Subscriptions By Donor
tags:
- Subscriptions
/api/v3/subscriptions:
get:
description: Returns all subscriptions for nonprofit
operationId: OpenApiSubscriptionsController_getSubscriptions
parameters:
- name: limit
required: false
in: query
description: The number of subscriptions to return.
schema:
minimum: 1
maximum: 100
default: 25
type: number
- name: maximumUpdatedDate
required: false
in: query
description: The maximum updated date of the subscriptions to return.
schema:
format: date-time
example: '2025-02-01'
type: string
- name: minimumUpdatedDate
required: false
in: query
description: The minimum updated date of the subscriptions to return.
schema:
format: date-time
example: '2025-01-01'
type: string
- name: page
required: false
in: query
description: The page number of the subscriptions to return.
schema:
minimum: 1
default: 1
type: number
- name: status
required: false
in: query
description: The status of the subscriptions to return.
schema:
example:
- active
type: array
items:
type: string
enum:
- active
- failed
- inactive
- paused
- pending
- recreated
- name: locationIds
required: false
in: query
description: Filter subscriptions by location Ids.
schema:
example:
- 6710f34fd5061afeec3eab57
type: array
items:
type: string
- name: sortBy
required: false
in: query
description: The field to sort the subscriptions by.
schema:
default: createdAt
example: createdAt
enum:
- amount
- createdAt
- frequency
- nextContributionAt
type: string
- name: sortDirection
required: false
in: query
description: The direction to sort the subscriptions by.
schema:
default: DESC
example: DESC
enum:
- ASC
- DESC
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetSubscriptionsResponse'
security:
- ClientId: []
ApiKey: []
summary: Get Subscriptions
tags:
- Subscriptions
/api/v3/subscriptions/{donorId}/{subscriptionId}:
get:
description: Returns a donor subscription by its Id.
operationId: OpenApiSubscriptionsController_getSubscriptionById
parameters:
- name: donorId
required: true
in: path
description: The Id of the donor to get the subscription for.
schema:
example: 2ea1ae03ca521e437db76d76
type: string
- name: subscriptionId
required: true
in: path
description: The Id of the subscription to get.
schema:
example: 2ea1ae03ca521e437db76d76
type: string
responses:
'200':
description: Subscription
content:
application/json:
schema:
$ref: '#/components/schemas/GetSubscriptionResponse'
'400':
description: Invalid request parameters
'404':
description: Subscription not found
security:
- ClientId: []
ApiKey: []
summary: Get Subscription By Id
tags:
- Subscriptions
patch:
description: Updates a donor subscription by its Id.
operationId: OpenApiSubscriptionsController_updateSubscriptionById
parameters:
- name: donorId
required: true
in: path
description: The Id of the donor to update the subscription for.
schema:
example: 2ea1ae03ca521e437db76d76
type: string
- name: subscriptionId
required: true
in: path
description: The Id of the subscription to update.
schema:
example: 2ea1ae03ca521e437db76d76
type: string
requestBody:
required: true
description: Subscription update details
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSubscriptionRequest'
responses:
'200':
description: Subscription updated successfully.
'400':
description: Updating the subscription failed
'404':
description: Subscription not found
security:
- ClientId: []
ApiKey: []
summary: Update Subscription
tags:
- Subscriptions
delete:
description: Cancels a donor subscription by its Id.
operationId: OpenApiSubscriptionsController_cancelSubscription
parameters:
- name: donorId
required: true
in: path
description: The Id of the donor to cancel the subscription for.
schema:
example: 2ea1ae03ca521e437db76d76
type: string
- name: subscriptionId
required: true
in: path
description: The Id of the subscription to cancel.
schema:
example: 2ea1ae03ca521e437db76d76
type: string
requestBody:
required: true
description: Subscription cancellation details
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteSubscriptionRequest'
responses:
'200':
description: Subscription cancelled successfully.
'400':
description: Invalid request parameters
'404':
description: Subscription not found
security:
- ClientId: []
ApiKey: []
summary: Cancel Subscription
tags:
- Subscriptions
components:
schemas:
GetSubscriptionResponse:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: Subscription Id.
example: 6710f34fd5061afeec3eab57
donorId:
type: string
description: Id of the Donor Profile.
example: 6710f34fd5061afeec3eab57
createdAt:
type: string
format: date-time
description: Subscription created at.
example: '2025-01-01T00:00:00.000Z'
updatedAt:
type: string
format: date-time
description: Subscription updated at.
example: '2025-01-01T00:00:00.000Z'
startDate:
type: string
format: date-time
description: Subscription start date.
example: '2025-01-01T00:00:00.000Z'
status:
type: string
enum:
- active
- failed
- inactive
- paused
- pending
- recreated
description: Subscription status.
example: active
amount:
type: number
description: Subscription amount.
example: 50
donorCoveredFees:
default: false
type: boolean
description: Whether the donor is covering fees.
example: false
anonymous:
type: boolean
description: Whether the donor wants the subscription to be anonymous.
example: false
frequency:
type: string
enum:
- biweekly
- monthly
- weekly
description: Subscription frequency.
example: weekly
nextPaymentDate:
type: string
format: date-time
nullable: true
description: Subscription next payment date.
example: '2025-01-01T00:00:00.000Z'
paymentMethod:
type: object
properties:
id:
type: string
holderName:
type: string
type:
type: string
enum:
- bank
- card
- wallet
last4:
type: string
expiration:
type: string
required:
- id
- type
- last4
- expiration
description: Subscription payment method.
example:
id: 6710f34fd5061afeec3eab57
holderName: John Doe
type: card
last4: '4242'
expiration: 12/2025
campaign:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
nullable: true
description: Campaign details for the contribution
example:
id: 7710f34fd5061afeec3eab78
name: Mission 2025
subcampaign:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
nullable: true
description: Subcampaign details for the contribution
example:
id: 7710f34fd5061afeec3eab79
name: Toy Drive
metadata:
type: object
additionalProperties:
type: string
nullable: true
description: Merchant-defined metadata.
example:
orderId: abc-123
locationId:
type: string
nullable: true
description: Id of the Location associated with the subscription.
example: 6710f34fd5061afeec3eab57
required:
- id
- donorId
- createdAt
- updatedAt
- startDate
- status
- amount
- anonymous
- frequency
- nextPaymentDate
- paymentMethod
- campaign
- subcampaign
description: Subscription.
required:
- data
CreateSubscriptionRequest:
type: object
properties:
paymentMethodId:
type: string
description: Id of the payment method.
example: 6710f34fd5061afeec3eab57
amount:
type: number
minimum: 0
exclusiveMinimum: true
description: Subscription amount in dollars.
example: 50
frequency:
type: string
enum:
- two-weeks
- 1st-15th
- month
- one-time
- week
description: Recurring frequency for the subscription.
example: month
startDate:
type: string
format: date-time
description: ISO 8601 date string when the subscription should start.
example: '2025-01-15T05:00:00.000Z'
timezone:
type: string
description: Timezone for the subscription start date. Defaults to UTC if not provided.
example: America/Chicago
anonymous:
type: boolean
description: Whether the donor wants the contribution to be anonymous.
example: false
campaignId:
type: string
description: Id of the campaign to allocate funds to
example: 7710f34fd5061afeec3eab78
subcampaignId:
type: string
description: Id of the subcampaign for more specific allocation.
example: 7710f34fd5061afeec3eab79
donorNotes:
type: string
description: Notes from the donor.
example: Happy to support this cause!
required:
- paymentMethodId
- amount
- frequency
NonprofitDonorProfileEntity:
type: object
properties: {}
UpdateSubscriptionRequest:
type: object
properties:
paymentMethodId:
type: string
description: Id of the payment method.
example: 6710f34fd5061afeec3eab57
amount:
type: number
minimum: 0
exclusiveMinimum: true
description: Subscription amount in dollars.
example: 50
startDate:
type: string
format: date-time
description: ISO 8601 date string when the subscription should start.
example: '2025-01-15T05:00:00.000Z'
timezone:
type: string
description: Timezone for the subscription start date. Defaults to UTC if not provided.
example: America/Chicago
anonymous:
type: boolean
description: Whether the donor wants the contribution to be anonymous.
example: false
campaignId:
type: string
description: Id of the campaign to allocate funds to
example: 7710f34fd5061afeec3eab78
subcampaignId:
type: string
description: Id of the subcampaign for more specific allocation.
example: 7710f34fd5061afeec3eab79
donorNotes:
type: string
description: Notes from the donor.
example: Happy to support this cause!
frequency:
type: string
enum:
- biweekly
- monthly
- weekly
GetSubscriptionsResponse:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: Subscription Id.
example: 6710f34fd5061afeec3eab57
donorId:
type: string
description: Id of the Donor Profile.
example: 6710f34fd5061afeec3eab57
createdAt:
type: string
format: date-time
description: Subscription created at.
example: '2025-01-01T00:00:00.000Z'
updatedAt:
type: string
format: date-time
description: Subscription updated at.
example: '2025-01-01T00:00:00.000Z'
startDate:
type: string
format: date-time
description: Subscription start date.
example: '2025-01-01T00:00:00.000Z'
status:
type: string
enum:
- active
- failed
- inactive
- paused
- pending
- recreated
description: Subscription status.
example: active
amount:
type: number
description: Subscription amount.
example: 50
donorCoveredFees:
default: false
type: boolean
description: Whether the donor is covering fees.
example: false
anonymous:
type: boolean
description: Whether the donor wants the subscription to be anonymous.
example: false
frequency:
type: string
enum:
- biweekly
- monthly
- weekly
description: Subscription frequency.
example: weekly
nextPaymentDate:
type: string
format: date-time
nullable: true
description: Subscription next payment date.
example: '2025-01-01T00:00:00.000Z'
paymentMethod:
type: object
properties:
id:
type: string
holderName:
type: string
type:
type: string
enum:
- bank
- card
- wallet
last4:
type: string
expiration:
type: string
required:
- id
- type
- last4
- expiration
description: Subscription payment method.
example:
id: 6710f34fd5061afeec3eab57
holderName: John Doe
type: card
last4: '4242'
expiration: 12/2025
campaign:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
nullable: true
description: Campaign details for the contribution
example:
id: 7710f34fd5061afeec3eab78
name: Mission 2025
subcampaign:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
nullable: true
description: Subcampaign details for the contribution
example:
id: 7710f34fd5061afeec3eab79
name: Toy Drive
metadata:
type: object
additionalProperties:
type: string
nullable: true
description: Merchant-defined metadata.
example:
orderId: abc-123
locationId:
type: string
nullable: true
description: Id of the Location associated with the subscription.
example: 6710f34fd5061afeec3eab57
required:
- id
- donorId
- createdAt
- updatedAt
- startDate
- status
- amount
- anonymous
- frequency
- nextPaymentDate
- paymentMethod
- campaign
- subcampaign
description: List of subscriptions.
totalCount:
type: number
description: Total number of subscriptions matching the filters.
example: 100
required:
- data
- totalCount
CreateSubscriptionResponse:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: Subscription Id.
example: 6710f34fd5061afeec3eab57
donorId:
type: string
description: Id of the Donor Profile.
example: 6710f34fd5061afeec3eab57
createdAt:
type: string
format: date-time
description: Subscription created at.
example: '2025-01-01T00:00:00.000Z'
updatedAt:
type: string
format: date-time
description: Subscription updated at.
example: '2025-01-01T00:00:00.000Z'
startDate:
type: string
format: date-time
description: Subscription start date.
example: '2025-01-01T00:00:00.000Z'
status:
type: string
enum:
- active
- failed
- inactive
- paused
- pending
- recreated
description: Subscription status.
example: active
amount:
type: number
description: Subscription amount.
example: 50
donorCoveredFees:
default: false
type: boolean
description: Whether the donor is covering fees.
example: false
anonymous:
type: boolean
description: Whether the donor wants the subscription to be anonymous.
example: false
frequency:
type: string
enum:
- biweekly
- monthly
- weekly
description: Subscription frequency.
example: weekly
nextPaymentDate:
type: string
format: date-time
nullable: true
description: Subscription next payment date.
example: '2025-01-01T00:00:00.000Z'
paymentMethod:
type: object
properties:
id:
type: string
holderName:
type: string
type:
type: string
enum:
- bank
- card
- wallet
last4:
type: string
expiration:
type: string
required:
- id
- type
- last4
- expiration
description: Subscription payment method.
example:
id: 6710f34fd5061afeec3eab57
holderName: John Doe
type: card
last4: '4242'
expiration: 12/2025
campaign:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
nullable: true
description: Campaign details for the contribution
example:
id: 7710f34fd5061afeec3eab78
name: Mission 2025
subcampaign:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
nullable: true
description: Subcampaign details for the contribution
example:
id: 7710f34fd5061afeec3eab79
name: Toy Drive
metadata:
type: object
additionalProperties:
type: string
nullable: true
description: Merchant-defined metadata.
example:
orderId: abc-123
locationId:
type: string
nullable: true
description: Id of the Location associated with the subscription.
example: 6710f34fd5061afeec3eab57
required:
- id
- donorId
- createdAt
- updatedAt
- startDate
- status
- amount
- anonymous
- frequency
- nextPaymentDate
- paymentMethod
- campaign
- subcampaign
description: The subscription that was created
required:
- data
DeleteSubscriptionRequest:
type: object
properties:
cancellationReason:
type: string
maxLength: 150
minLength: 1
description: The reason for cancelling the subscription.
example: I no longer attend this organization.
securitySchemes:
ApiKey:
type: apiKey
in: header
name: x-api-key
description: API Key for API authentication
ClientId:
type: apiKey
in: header
name: x-client-id
description: Client ID for API authentication