# Create a store credit entry

### POS&#x54;**:** /wp-json/wc-store-credits/v1/entries‌ <a href="#post-wp-json-loyalty-program-v-1-customers-points-user_id" id="post-wp-json-loyalty-program-v-1-customers-points-user_id"></a>

{% tabs %}
{% tab title="Request" %}
**Requirements:**

* Logged-in user
* user role with `manage_woocommerce` user capability

| Method | Endpoint                              |
| ------ | ------------------------------------- |
| POST   | /wp-json/wc-store-credits/v1/entries‌ |

<table><thead><tr><th width="200">Parameters</th><th width="188">Required</th><th>Type</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td>amount</td><td>yes</td><td>float</td><td>-</td><td>Entry amount value. Must always be a positive value.</td></tr><tr><td>user_id</td><td>yes</td><td>integer</td><td>-</td><td>Customer ID</td></tr><tr><td>type</td><td>yes</td><td>string</td><td>-</td><td>Entry type: <code>increase</code> or <code>decrease</code></td></tr><tr><td>action</td><td>yes</td><td>string</td><td>-</td><td>The action or source slug of the entry.<br><br>This requires a valid source/action that is registered by code (<a href="#source-action-types">see below</a>).</td></tr><tr><td>date</td><td>no</td><td>string</td><td><em>current date &#x26; time</em></td><td>Date and time the entry was created</td></tr><tr><td>date_format</td><td>no</td><td>string</td><td>Y-m-d H:i:s</td><td><p>Date format of the provided date values.</p><p>See: <a href="https://www.php.net/manual/en/datetime.format.php">https://www.php.net/manual/en/datetime.format.php</a></p></td></tr><tr><td>object_id</td><td>no</td><td>integer</td><td>0</td><td>The ID of related object of the entry. This can either be the  ID of an order, coupon, user or post.</td></tr></tbody></table>

{% endtab %}

{% tab title="Request Example" %}
Create a store credit entry

```
POST: http://example.com/wp-json/wc-store-credits/v1/entry

{
    "user_id": 10,
    "amount": 30.25,
    "type": "increase",
    "action": "admin_increase",
    "object_id": 1
}
```

\
**Invalid:** create a store credit entry with missing parameter

```
POST: http://example.com/wp-json/wc-store-credits/v1/entry

{
    "user_id": 10,
    "amount": 100,
    "type": "increase",
    "action": "admin_increase"
}
```

\
**Invalid:** create a store credit entry with negative amount

```
POST: http://example.com/wp-json/wc-store-credits/v1/entry

{
    "user_id": 10,
    "amount": -100,
    "type": "decrease",
    "action": "gift_card",
    "object_id": 10
}
```

\
**Invalid:** create a store credit entry for non-existing user

```
POST: http://example.com/wp-json/wc-store-credits/v1/entry

{
    "user_id": 999,
    "amount": 100,
    "type": "increase",
    "action": "admin_increase",
    "object_id": 1
}
```

{% endtab %}

{% tab title="Response Example" %}
**Status: 200 OK**

```
{
  "message": "Successfully created store credit entry.",
  "data": {
    "key": "37",
    "id": 37,
    "amount_raw": 30.25,
    "amount": "$30.25",
    "type": "increase",
    "activity": "Admin adjustment (increase)",
    "user_id": 1,
    "date": "",
    "rel_link": "",
    "rel_label": "-",
    "note": ""
  },
  "balance_raw": 295.25,
  "balance": "$295.25"
}
```

\
**Status: 400 Bad Request**

```
{
    "code": "store_credit_entry_missing_params",
    "message": "Unable to save store credit entry due to missing or invalid required parameters.",
    "data": {
        "status": 400,
        "data": {
            "user_id": 10,
            "amount": 100,
            "type": "increase",
            "action": "admin_increase"
        }
    }
}
```

**Status: 400 Bad Request**

```
{
    "code": "store_credit_entry_missing_params",
    "message": "Unable to save store credit entry due to missing or invalid required parameters.",
    "data": {
        "status": 400,
        "data": {
            "user_id": 10,
            "amount": -100,
            "type": "decrease",
            "action": "gift_card",
            "object_id": 10
        }
    }
}
```

**Status: 400 Bad Request**

```
{
    "code": "store_credit_entry_missing_params",
    "message": "Unable to save store credit entry due to missing or invalid required parameters.",
    "data": {
        "status": 400,
        "data": {
            "user_id": 999,
            "amount": 100,
            "type": "increase",
            "action": "admin_increase",
            "object_id": 1
        }
    }
}
```

\
**Status: 403 Forbidden**

```
{
    "code": "rest_forbidden_context",
    "message": "Sorry, you are not allowed access to this endpoint.",
    "data": {
        "status": 401
    }
}

```

{% endtab %}
{% endtabs %}

## Source / Action Types

Store credits only supports a handful of source and action types.&#x20;

{% hint style="info" %}
**Source type** refers to which source the increase in the user's store credit is coming from. (e.g. refunds, cashback, gift cards, etc.)
{% endhint %}

{% hint style="info" %}
Action type refers to actions that the deduct a user's store credit. (e.g. discount, admin decrease, etc.)
{% endhint %}

Source and action types needs to be registered in the code via a filter for it to be recognized as valid source/action type.

### Pre-defined source types:

| Source Type       | Label                       | Description                                                                                                                                                            |
| ----------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `refund`          | Refunded order              | Usually added when an order's paid amount is refunded as store credits.                                                                                                |
| `gift_card`       | Purchased gift cards        | Added when a gift card code is redeemed as store credits.                                                                                                              |
| `admin_increase`  | Admin adjustment (increase) | Added when an admin user manually increases a customer's store credits.                                                                                                |
| `cancelled_order` | Cancelled order             | Refers to the store credits, which was used in an order that was cancelled, and was added back to their store credit balance.                                          |
| `cashback_coupon` | Cashback coupon             | <p>The store credits earned after completing an order with a cashback coupon applied. <br><br><em>(Requires the Advanced Coupons premium plugin to be active)</em></p> |
| `loyalty_points`  | Loyalty Points              | <p>Refers to the store credits earned after a customer redeems their loyalty points.<br><br><em>(Required the Loyalty Program plugin to be active)</em></p>            |

### Pre-defined action types:

| Action type      | Label                       |                                                                   |
| ---------------- | --------------------------- | ----------------------------------------------------------------- |
| `discount`       | Order Discount              | The amount of store credits used as payment/discount in an order. |
| `admin_decrease` | Admin adjustment (decrease) | The amount of store credits deducted by an admin                  |

## Registering custom point sources

To register custom point sources, third party plugins will need to utilize the `lpfw_get_point_earn_source_types` filter. The filter's value expects an array list of point sources that a follows a specific schema.

### Using the filter example:

```php
add_filter('acfw_get_store_credits_increase_source_types', 'example_register_store_credit_sources');
function example_register_store_credit_sources($registry) {

    // add custom sources.
    // the array key must have the same value with the slug.
    $registry['refer_a_friend'] = array(
        'name'    => 'Refer a friend',
        'slug'    => 'refer_a_friend',
        'related' => array(
            'object_type'         => 'user',
            'admin_label'         => 'View referred user',
            'label'               => 'Refer a friend',
            'admin_link_callback' => 'get_edit_user_link',
            'link_callback'       => '',
        ),
    );
    
    return $registry;
}
```

### Point source schema:

<table><thead><tr><th width="196.039603960396">Property key</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td>The user friendly name of the point source. This is used in the points sources table in admin and on the points history table in both admin and my points page.</td></tr><tr><td>slug</td><td>This is the unique identifier of the points source. This value should also be the same with they key set in the main array.</td></tr><tr><td>related</td><td>This holds the values, labels, and callbacks that is used to display the related column in the points history table.</td></tr></tbody></table>

### Related property schema:

<table><thead><tr><th width="150.0935234244077">Property Key</th><th width="150">Value type</th><th>Description</th></tr></thead><tbody><tr><td>object_type</td><td>string</td><td>The type of object of the related ID set for the point entry. Accepted values are user, order, comment, and coupon.</td></tr><tr><td>admin_label</td><td>string</td><td>The label to display for the related column in the points history table in the admin.</td></tr><tr><td>label</td><td>string</td><td>The label to display for the related column in the points history table in the my points page.</td></tr><tr><td>admin_link_callback</td><td>string | array</td><td><p>The callback used to generate a link for the related column for admins. It is highly recommended to link them to the relative view/edit page of the object. You can use either of the following callbacks available by default in WordPress:</p><p>get_edit_post_link</p><p>get_comment_link</p><p>get_edit_user_link</p></td></tr><tr><td>link_callback</td><td>string | array</td><td>The callback used to generate a link for the related column for the my points page. It is highly recommended to link them to the frontend view of the relative object if it's available and can be accessed by the logged-in customer.</td></tr></tbody></table>