openapi: 3.1.0
info:
  title: API Reference subpackage_advertisement_opportunities subpackage_bulk_subscriptions API
  version: 1.0.0
servers:
- url: https://api.beehiiv.com/v2
tags:
- name: subpackage_bulk_subscriptions
paths:
  /publications/{publicationId}/bulk_subscriptions:
    post:
      operationId: create
      summary: 'Bulk create subscription <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:write</Badge>'
      description: Create new subscriptions for a publication.
      tags:
      - subpackage_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'
        '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_: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. <Badge intent="warning" minimal outlined>Beta</Badge>
        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. <Badge intent="warning" minimal outlined>Beta</Badge>
      required:
      - email
      title: SubscriptionRequest
    type_:SubscriptionsCreateRequestTier:
      type: string
      enum:
      - free
      - premium
      description: The tier for this subscription.
      title: SubscriptionsCreateRequestTier
    type_:DoubleOptOverride:
      type: string
      description: Override publication double-opt settings for this subscription.
      title: DoubleOptOverride
    type_ids:PublicationId:
      type: string
      description: The prefixed ID of the publication.
      title: PublicationId
    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_: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
    type_:ErrorDetail:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
      required:
      - message
      - code
      title: ErrorDetail
    type_:CustomFieldDataType:
      oneOf:
      - type: string
      - type: number
        format: double
      - type: boolean
      - type: array
        items:
          type: string
      title: CustomFieldDataType
    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:OptionalStripeCustomerId:
      type: string
      description: The prefixed ID of the Stripe customer.
      title: OptionalStripeCustomerId
  securitySchemes:
    BearerAuthScheme:
      type: http
      scheme: bearer