beehiiv Bulk Subscriptions API

openapi: 3.2.0
info:
  title: Reference Bulk Subscriptions API
  version: 1.0.0
servers:
- url: https://api.beehiiv.com/v2
  description: Default
tags:
- name: Bulk Subscriptions
paths:
  /publications/{publicationId}/bulk_subscriptions:
    post:
      operationId: create
      summary: 'Bulk create subscription OAuth Scope: subscriptions:write'
      description: Create new subscriptions for a publication.
      tags:
      - Bulk Subscriptions
      parameters:
      - name: publicationId
        in: path
        description: The prefixed ID of the publication object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_PublicationId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Subscriptions created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_bulk_subscriptions_BulkSubscriptionCreateResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '401':
          description: Unauthorized. The API key or OAuth access token is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                subscriptions:
                  type: array
                  items:
                    $ref: '#/components/schemas/type__SubscriptionRequest'
              required:
              - subscriptions
components:
  schemas:
    type__CustomFieldDataType:
      oneOf:
      - type: string
      - type: number
        format: double
      - type: boolean
      - type: array
        items:
          type: string
      title: CustomFieldDataType
    type_ids_PublicationId:
      type: string
      description: The prefixed ID of the publication.
      title: PublicationId
    type__CustomFieldValue:
      type: object
      properties:
        name:
          type: string
          description: The name of the existing custom field
        value:
          $ref: '#/components/schemas/type__CustomFieldDataType'
          description: The value stored for the subscription
      description: The object required for setting custom field values on a subscription
      title: CustomFieldValue
    type_ids_ComplimentaryAccessId:
      type: string
      description: The prefixed ID of the complimentary access object.
      title: ComplimentaryAccessId
    type_bulk_subscriptions_BulkSubscriptionCreateResponse:
      type: object
      properties:
        message:
          type: string
          description: The result of the create request
        import_id:
          type: string
          description: The database ID of the import object created from the Bulk Subscription Create request
      required:
      - message
      - import_id
      description: The response containing the import ID
      title: BulkSubscriptionCreateResponse
    type__SubscriptionRequest:
      type: object
      properties:
        email:
          type: string
          description: The email address of the subscription.
        reactivate_existing:
          type: boolean
          default: false
          description: Whether or not to reactivate the subscription if they have already unsubscribed. This option should be used only if the subscriber is knowingly resubscribing.
        send_welcome_email:
          type: boolean
          default: false
        utm_source:
          type: string
          description: The source of the subscription.
        utm_medium:
          type: string
          description: The medium of the subscription
        utm_campaign:
          type: string
          description: The acquisition campaign of the subscription
        utm_term:
          type: string
          description: The acquisition term; typically the keyword or search term
        utm_content:
          type: string
          description: The acquisition content; typically used for A/B testing or ad variations
        referring_site:
          type: string
          description: The website that the subscriber was referred from
        referral_code:
          type: string
          description: This should be a subscribers referral_code. This gives referral credit for the new subscription.
        custom_fields:
          type: array
          items:
            $ref: '#/components/schemas/type__CustomFieldValue'
          description: The custom fields must already exist for the publication. Any new custom fields here will be discarded.
        double_opt_override:
          $ref: '#/components/schemas/type__DoubleOptOverride'
          description: 'Override the publication''s default double opt-in settings for this subscription. Possible values are:

            - "on" — The subscriber will receive a double opt-in confirmation email and will need to confirm their subscription prior to being marked as active.

            - "off" — The subscriber will be marked as active immediately and will not receive a double opt-in confirmation email.

            - "not_set" — The publication''s default double opt-in settings will be applied to this subscription.'
        tier:
          $ref: '#/components/schemas/type__SubscriptionsCreateRequestTier'
          description: The tier for this subscription.
        premium_tiers:
          type: array
          items:
            type: string
          description: An array of premium tier names to assign to this subscription. When provided, the subscription will be assigned to premium tiers matching these names. Can be combined with `premium_tier_ids` to include tiers from both (duplicates are removed). Takes precedence over the `tier` parameter.
        premium_tier_ids:
          type: array
          items:
            type: string
          description: An array of premium tier IDs to assign to this subscription. When provided, the subscription will be assigned to these specific premium tiers. Can be combined with `premium_tiers` to include tiers from both (duplicates are removed). Takes precedence over the `tier` parameter.
        stripe_customer_id:
          $ref: '#/components/schemas/type_ids_OptionalStripeCustomerId'
          description: The Stripe customer ID for this subscription.
        automation_ids:
          type: array
          items:
            type: string
          description: Enroll the subscriber into automations after their subscription has been created. Requires the automations to have an active *Add by API* trigger.
        newsletter_list_ids:
          type: array
          items:
            type: string
          description: An array of newsletter list prefixed IDs to subscribe the new subscription to. The newsletter lists must belong to the same publication.
        skip_newsletter_list_auto_subscribe:
          type: boolean
          description: When true, the subscriber will not be auto-subscribed to newsletter lists configured with auto-subscribe. Defaults to false.
        complimentary_gift_id:
          $ref: '#/components/schemas/type_ids_ComplimentaryAccessId'
          description: The prefixed ID of a complimentary access object to apply to this subscription. The complimentary access must belong to the same publication.
      required:
      - email
      title: SubscriptionRequest
    type__DoubleOptOverride:
      type: string
      description: Override publication double-opt settings for this subscription.
      title: DoubleOptOverride
    type_ids_OptionalStripeCustomerId:
      type: string
      description: The prefixed ID of the Stripe customer.
      title: OptionalStripeCustomerId
    type__ErrorDetail:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
      required:
      - message
      - code
      title: ErrorDetail
    type__SubscriptionsCreateRequestTier:
      type: string
      enum:
      - free
      - premium
      description: The tier for this subscription.
      title: SubscriptionsCreateRequestTier
    type__Error:
      type: object
      properties:
        status:
          type: integer
        statusText:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/type__ErrorDetail'
      required:
      - status
      - statusText
      - errors
      description: The top level error response.
      title: Error
  securitySchemes:
    BearerAuthScheme:
      type: http
      scheme: bearer