About the Join Applications API

The Join Applications API manages the complete workflow for program participation, from initial application or invitation through approval and payment processing to final enrollment. It supports both member-initiated applications where users request to join programs, and owner-initiated invitations where program owners invite specific members to participate.

With the Join Applications API, you can:

• Create and manage join applications for program participation.
• Handle both member-initiated applications and owner-initiated invitations.
• Process approval workflows with status transitions.
• Integrate payment processing for paid programs.
• Apply and manage coupons for program discounts.
• Automatically create program participants upon successful completion.
• Bulk manage applications and invitations efficiently.

The API integrates seamlessly with Wix's member ecosystem, payment systems, and pricing plans to provide a complete program enrollment solution. Join applications maintain a comprehensive audit trail through status change events and support both one-time payments and subscription-based program access.

Before you begin

It's important to note the following points before starting to code:

• Programs must be in PUBLISHED status to accept applications.
• Only one join application is allowed per member per program.
• Status transitions are unidirectional and status-specific (for example, you can only approve APPROVAL_PENDING applications).
• Payment operations require specific app installations (Online Programs, Pricing Plans).
• Bulk operations are limited to 100 items per request.
• DECLINED and CANCELLED are terminal statuses. The service removes applications in either status asynchronously.
• Members use Get Current Join Application to retrieve their own application. Apps tracking an application by ID can use Get Join Application, Query Join Applications, or Search Join Applications.

Use cases

This API supports these primary business flows:

• Handle member-initiated program applications - Members apply to join programs and wait for owner approval.
• Manage owner-initiated program invitations - Program owners invite specific members to participate.
• Process program payments and discounts - Handle payment preparation, coupon application, and payment completion.
• Bulk manage applications and invitations - Efficiently process large numbers of applications using bulk operations, filters, tags, and async job tracking.

Terminology

• Join Application - A business entity representing the complete workflow from program application or invitation to enrollment.
• Status - The current state of the application (INVITED, APPROVAL_PENDING, APPROVED, CANCELLED, DECLINED, SUSPENDED).
• Payment Status - The payment processing state. See Payment Status Definitions for details.
• Member Flow - Self-service operations where members manage their own applications.
• Owner Flow - Administrative operations where program owners manage applications for others.
• Participant - The resulting entity created when a join application is successfully completed (APPROVED status with NO_PAYMENT_REQUIRED or PAYMENT_SUCCESSFUL).

Payment Status Definitions

The payment_status field tracks the payment lifecycle for a join application:

Payment Flows

This section describes the payment flows from both member and owner perspectives.

Flow 1: Free Program (No Payment Required)

When a program has no price and no connected pricing plans, the join application is created with NO_PAYMENT_REQUIRED status.

Member perspective:

1. Member calls CreateJoinApplication for a free program.
2. Join application is created with payment_status: NO_PAYMENT_REQUIRED.
3. If the program is public (no approval required), status is set to APPROVED and a participant is automatically created.
4. If the program is private, status is set to APPROVAL_PENDING and the owner must approve.

Status transitions:

Flow 2: Single Payment (One-Time Payment)

When a program has a price, members must complete payment before becoming participants.

Member perspective:

1. Member calls CreateJoinApplication for a paid program.
2. Join application is created with payment_status: PAYMENT_PENDING.
3. Member calls PreparePayment with payment_type: SINGLE_PAYMENT.
4. The system first checks whether the member has an eligible Pricing Plans entitlement for the program. If one exists, it returns PAYMENT_SUCCESSFUL and no checkout is needed.
5. Otherwise, the system creates a cashier order and sets payment_status: PAYMENT_IN_PROGRESS.
6. Use the returned paymentInfo.paymentOrderId with the Wix payment checkout flow.
7. Subscribe to Join Applications domain events to receive the payment outcome, or retrieve the application by ID to check its current state.
8. Upon successful payment, payment_status becomes PAYMENT_SUCCESSFUL.
9. If status is APPROVED, a participant is automatically created.

Status transitions:

Error scenarios:

• MISSING_PAYMENT_ORDER: PreparePayment was not called before attempting payment operations.
• INVALID_PAYMENT_STATUS: Payment operation attempted in an invalid state. PreparePayment is supported from PAYMENT_PENDING, PAYMENT_FAILED, and PAYMENT_CANCELED; an already successful Pricing Plans payment can be returned without creating a new checkout.

Flow 3: Pricing Plans Payment

When a program is connected to pricing plans, members can pay through plan subscriptions.

Member perspective:

1. Member calls CreateJoinApplication for a program with connected pricing plans.
2. If member already has an eligible plan, payment_status: PAYMENT_SUCCESSFUL and plan IDs in payment_info.paid_plan_ids.
3. If member needs to purchase a plan, payment_status: PAYMENT_PENDING.
4. Member calls PreparePayment with payment_type: PAID_PLANS.
5. The system first checks for an eligible entitlement. If it finds one, it repairs a stale PAYMENT_PENDING application to PAYMENT_SUCCESSFUL and returns the eligible plan IDs. No purchase is needed, even if that plan is no longer available for purchase.
6. If no eligible entitlement exists, the system validates that pricing plans are connected and sets payment_status: PAYMENT_IN_PROGRESS.
7. Member completes plan purchase through Pricing Plans.
8. Upon successful purchase, payment_status becomes PAYMENT_SUCCESSFUL with plan IDs in payment_info.paid_plan_ids.

Status transitions:

Error scenarios:

• NO_PAID_PLAN_CONNECTED: No pricing plans are connected to the program.
• PRICING_PLANS_NOT_INSTALLED: Pricing Plans app is not installed on the site.

Flow 4: Offline Payment (Owner Approval Required)

Offline payments allow members to pay through manual methods (cash, check, bank transfer). The site owner must approve these transactions.

Member perspective:

1. Member creates join application with payment_status: PAYMENT_PENDING.
2. Member initiates offline payment through the checkout.
3. System receives OfflineTransactionCreated event.
4. payment_status changes to PENDING_OWNER_APPROVAL.
5. Member waits for owner to approve or decline the transaction.

Owner perspective:

1. Owner sees pending offline transactions in the dashboard.
2. Owner approves the transaction → payment_status: PAYMENT_SUCCESSFUL → Participant created.
3. Or owner declines/cancels the transaction → payment_status: PAYMENT_FAILED → Join application is cleaned up.

Status transitions:

Flow 5: Coupon Application

Coupons can be applied to reduce the payment amount during checkout.

Member perspective:

1. Join application is in payment_status: PAYMENT_IN_PROGRESS (after PreparePayment).
2. Member calls ApplyCoupon with the coupon code.
3. System validates the coupon and applies it to the payment order.
4. payment_info.coupon_id is populated with the applied coupon ID.
5. Member completes payment with the discounted amount.
6. Upon successful payment, the coupon is automatically redeemed.

Status transitions:

Retry after a failed or canceled payment:

ApplyCoupon, RemoveCoupon, and CompleteFreeCouponPayment are also accepted when payment_status is PAYMENT_FAILED or PAYMENT_CANCELED. This lets a member set up or change a coupon and retry without first calling PreparePayment.

If the coupon makes the order free, the retry can be closed out directly:

Error scenarios:

• COUPON_NOT_FOUND: The coupon code is invalid.
• COUPON_ALREADY_APPLIED: A coupon is already applied to this order.
• MISSING_PAYMENT_ORDER: No payment order exists to apply the coupon to.
• INVALID_PAYMENT_STATUS: Coupon operation attempted in an invalid state. ApplyCoupon, RemoveCoupon, and CompleteFreeCouponPayment are supported from PAYMENT_IN_PROGRESS, PAYMENT_FAILED, and PAYMENT_CANCELED.

Participant Creation

A participant is automatically created when both conditions are met:

1. status is APPROVED
2. payment_status is either NO_PAYMENT_REQUIRED or PAYMENT_SUCCESSFUL

The participant_id field is populated on the join application once the participant is created, linking the application to the resulting participant entity.