Create a store credit entry

POST: /wp-json/wc-store-credits/v1/entries‌

Request

Requirements:

• Logged-in user

• user role with manage_woocommerce user capability

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

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

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
}

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
    }
}

Source / Action Types

Store credits only supports a handful of source and action types.

Source type refers to which source the increase in the user's store credit is coming from. (e.g. refunds, cashback, gift cards, etc.)

Action type refers to actions that the deduct a user's store credit. (e.g. discount, admin decrease, etc.)

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	The store credits earned after completing an order with a cashback coupon applied. (Requires the Advanced Coupons premium plugin to be active)
loyalty_points	Loyalty Points	Refers to the store credits earned after a customer redeems their loyalty points. (Required the Loyalty Program plugin to be active)

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:

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:

Property key	Description
name	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.
slug	This is the unique identifier of the points source. This value should also be the same with they key set in the main array.
related	This holds the values, labels, and callbacks that is used to display the related column in the points history table.

Related property schema:

Property Key	Value type	Description
object_type	string	The type of object of the related ID set for the point entry. Accepted values are user, order, comment, and coupon.
admin_label	string	The label to display for the related column in the points history table in the admin.
label	string	The label to display for the related column in the points history table in the my points page.
admin_link_callback	string | array	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: get_edit_post_link get_comment_link get_edit_user_link
link_callback	string | array	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.