# Joining the loyalty program

Please use the [Connections endpoint](https://www.perkville.com/developers/docs/v2/#v2_resource_7_anchor) to faciliate a customer joining the loyalty program. You would change the Connection status to Active. 

### Agreements

Businesses can set [Agreements](/features/settings/advanced/agreements.md) that must be agreed to prior to joining the loyalty program. If these restrictions are in place, you'll need to perform a few additional steps before attempting to join on the user's behalf.

* [Fetch Agreements](https://www.perkville.com/developers/docs/v2/#v2_rewards_program_user_agreements_view_anchor) that are applicable to joining the loyalty program, and present them to the user. 

```http
curl "https://api.perkville.com/v2/agreements-view/?business=25&user_id=1234&apply_to_join_flow=true" -H "Authorization: Bearer accesstoken123abc"
```

{% hint style="info" %}
The text field may have hyperlinks in the form of `[this is a link](https://example.com)` so you will want to care when rendering this text field.
{% endhint %}

* Once the user agrees to the terms, post the acceptance via the [batch agreement endpoint](https://www.perkville.com/developers/docs/v2/#v2_batch_2_anchor).
* Finally, join via the [Connections endpoint](https://www.perkville.com/developers/docs/v2/#v2_resource_7_anchor)

### Caveats

1. You **cannot create new Connections** via the Connection endpoint. If a Connection does not already exist, the join attempt will fail.
2. `status` only accepts **ACTIVE** or **INACTIVE**.
3. Scope rules apply. With `USER_CUSTOMER_INFO`, a user can only update their own Connection. With `ADMIN_CUSTOMER_INFO`, staff can update Connections for their business.

### Validation errors (customer-safe copy)

Below are the join-related validation errors that may be returned when setting `status=ACTIVE`, plus recommended customer-safe messages.

* `pv_connection_membership_not_active`

  When: The business requires an active membership and the customer’s membership is not active.\
  Customer-safe: “Your membership is not active. Please contact the business for help.”
* `pv_agreement_required`\
  When: The business requires agreement terms and the customer has not agreed. They will need to review accept the business' terms on the Perkville site before being able to join.\
  Customer-safe: “Please review and accept the required terms to join at {business.perkville\_url}"


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.perkville.com/overview/integrations/integrating-perkville/integrating-your-app-with-perkville/joining-the-loyalty-program.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.